diff options
Diffstat (limited to 'usr/src/man/man3nsl')
81 files changed, 21322 insertions, 0 deletions
diff --git a/usr/src/man/man3nsl/Makefile b/usr/src/man/man3nsl/Makefile new file mode 100644 index 0000000000..1597916b90 --- /dev/null +++ b/usr/src/man/man3nsl/Makefile @@ -0,0 +1,573 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3nsl + +MANFILES = dial.3nsl \ + doconfig.3nsl \ + gethostbyname.3nsl \ + getipsecalgbyname.3nsl \ + getipsecprotobyname.3nsl \ + getnetconfig.3nsl \ + getnetpath.3nsl \ + getpublickey.3nsl \ + getrpcbyname.3nsl \ + netdir.3nsl \ + nlsgetcall.3nsl \ + nlsprovider.3nsl \ + nlsrequest.3nsl \ + rpc.3nsl \ + rpc_clnt_auth.3nsl \ + rpc_clnt_calls.3nsl \ + rpc_clnt_create.3nsl \ + rpc_control.3nsl \ + rpc_gss_get_error.3nsl \ + rpc_gss_get_mechanisms.3nsl \ + rpc_gss_get_principal_name.3nsl \ + rpc_gss_getcred.3nsl \ + rpc_gss_max_data_length.3nsl \ + rpc_gss_mech_to_oid.3nsl \ + rpc_gss_seccreate.3nsl \ + rpc_gss_set_callback.3nsl \ + rpc_gss_set_defaults.3nsl \ + rpc_gss_set_svc_name.3nsl \ + rpc_soc.3nsl \ + rpc_svc_calls.3nsl \ + rpc_svc_create.3nsl \ + rpc_svc_err.3nsl \ + rpc_svc_input.3nsl \ + rpc_svc_reg.3nsl \ + rpc_xdr.3nsl \ + rpcbind.3nsl \ + rpcsec_gss.3nsl \ + secure_rpc.3nsl \ + t_accept.3nsl \ + t_alloc.3nsl \ + t_bind.3nsl \ + t_close.3nsl \ + t_connect.3nsl \ + t_errno.3nsl \ + t_error.3nsl \ + t_free.3nsl \ + t_getinfo.3nsl \ + t_getprotaddr.3nsl \ + t_getstate.3nsl \ + t_listen.3nsl \ + t_look.3nsl \ + t_open.3nsl \ + t_optmgmt.3nsl \ + t_rcv.3nsl \ + t_rcvconnect.3nsl \ + t_rcvdis.3nsl \ + t_rcvrel.3nsl \ + t_rcvreldata.3nsl \ + t_rcvudata.3nsl \ + t_rcvuderr.3nsl \ + t_rcvv.3nsl \ + t_rcvvudata.3nsl \ + t_snd.3nsl \ + t_snddis.3nsl \ + t_sndrel.3nsl \ + t_sndreldata.3nsl \ + t_sndudata.3nsl \ + t_sndv.3nsl \ + t_sndvudata.3nsl \ + t_strerror.3nsl \ + t_sync.3nsl \ + t_sysconf.3nsl \ + t_unbind.3nsl \ + xdr.3nsl \ + xdr_admin.3nsl \ + xdr_complex.3nsl \ + xdr_create.3nsl \ + xdr_simple.3nsl \ + yp_update.3nsl \ + ypclnt.3nsl + +MANSOFILES = auth_destroy.3nsl \ + authdes_create.3nsl \ + authdes_getucred.3nsl \ + authdes_seccreate.3nsl \ + authnone_create.3nsl \ + authsys_create.3nsl \ + authsys_create_default.3nsl \ + authunix_create.3nsl \ + authunix_create_default.3nsl \ + callrpc.3nsl \ + clnt_broadcast.3nsl \ + clnt_call.3nsl \ + clnt_control.3nsl \ + clnt_create.3nsl \ + clnt_create_timed.3nsl \ + clnt_create_vers.3nsl \ + clnt_create_vers_timed.3nsl \ + clnt_destroy.3nsl \ + clnt_dg_create.3nsl \ + clnt_door_create.3nsl \ + clnt_freeres.3nsl \ + clnt_geterr.3nsl \ + clnt_pcreateerror.3nsl \ + clnt_perrno.3nsl \ + clnt_perror.3nsl \ + clnt_raw_create.3nsl \ + clnt_send.3nsl \ + clnt_spcreateerror.3nsl \ + clnt_sperrno.3nsl \ + clnt_sperror.3nsl \ + clnt_tli_create.3nsl \ + clnt_tp_create.3nsl \ + clnt_tp_create_timed.3nsl \ + clnt_vc_create.3nsl \ + clntraw_create.3nsl \ + clnttcp_create.3nsl \ + clntudp_bufcreate.3nsl \ + clntudp_create.3nsl \ + endhostent.3nsl \ + endnetconfig.3nsl \ + endnetpath.3nsl \ + endrpcent.3nsl \ + freeipsecalgent.3nsl \ + freenetconfigent.3nsl \ + get_myaddress.3nsl \ + gethostbyaddr.3nsl \ + gethostbyaddr_r.3nsl \ + gethostbyname_r.3nsl \ + gethostent.3nsl \ + gethostent_r.3nsl \ + getipsecalgbynum.3nsl \ + getipsecprotobynum.3nsl \ + getnetconfigent.3nsl \ + getnetname.3nsl \ + getrpcbyname_r.3nsl \ + getrpcbynumber.3nsl \ + getrpcbynumber_r.3nsl \ + getrpcent.3nsl \ + getrpcent_r.3nsl \ + getrpcport.3nsl \ + getsecretkey.3nsl \ + host2netname.3nsl \ + key_decryptsession.3nsl \ + key_encryptsession.3nsl \ + key_gendes.3nsl \ + key_secretkey_is_set.3nsl \ + key_setsecret.3nsl \ + nc_perror.3nsl \ + nc_sperror.3nsl \ + netdir_free.3nsl \ + netdir_getbyaddr.3nsl \ + netdir_getbyname.3nsl \ + netdir_mergeaddr.3nsl \ + netdir_options.3nsl \ + netdir_perror.3nsl \ + netdir_sperror.3nsl \ + netname2host.3nsl \ + netname2user.3nsl \ + pmap_getmaps.3nsl \ + pmap_getport.3nsl \ + pmap_rmtcall.3nsl \ + pmap_set.3nsl \ + pmap_unset.3nsl \ + publickey.3nsl \ + registerrpc.3nsl \ + rpc_broadcast.3nsl \ + rpc_broadcast_exp.3nsl \ + rpc_call.3nsl \ + rpc_createerr.3nsl \ + rpc_gss_get_mech_info.3nsl \ + rpc_gss_get_versions.3nsl \ + rpc_gss_is_installed.3nsl \ + rpc_gss_qop_to_num.3nsl \ + rpc_gss_svc_max_data_length.3nsl \ + rpc_reg.3nsl \ + rpcb_getaddr.3nsl \ + rpcb_getmaps.3nsl \ + rpcb_gettime.3nsl \ + rpcb_rmtcall.3nsl \ + rpcb_set.3nsl \ + rpcb_unset.3nsl \ + sethostent.3nsl \ + setnetconfig.3nsl \ + setnetpath.3nsl \ + setrpcent.3nsl \ + svc_add_input.3nsl \ + svc_auth_reg.3nsl \ + svc_control.3nsl \ + svc_create.3nsl \ + svc_destroy.3nsl \ + svc_dg_create.3nsl \ + svc_dg_enablecache.3nsl \ + svc_done.3nsl \ + svc_door_create.3nsl \ + svc_exit.3nsl \ + svc_fd_create.3nsl \ + svc_fd_negotiate_ucred.3nsl \ + svc_fds.3nsl \ + svc_fdset.3nsl \ + svc_freeargs.3nsl \ + svc_getargs.3nsl \ + svc_getcaller.3nsl \ + svc_getcallerucred.3nsl \ + svc_getreq.3nsl \ + svc_getreq_common.3nsl \ + svc_getreq_poll.3nsl \ + svc_getreqset.3nsl \ + svc_getrpccaller.3nsl \ + svc_max_pollfd.3nsl \ + svc_pollfd.3nsl \ + svc_raw_create.3nsl \ + svc_reg.3nsl \ + svc_register.3nsl \ + svc_remove_input.3nsl \ + svc_run.3nsl \ + svc_sendreply.3nsl \ + svc_tli_create.3nsl \ + svc_tp_create.3nsl \ + svc_unreg.3nsl \ + svc_unregister.3nsl \ + svc_vc_create.3nsl \ + svcerr_auth.3nsl \ + svcerr_decode.3nsl \ + svcerr_noproc.3nsl \ + svcerr_noprog.3nsl \ + svcerr_progvers.3nsl \ + svcerr_systemerr.3nsl \ + svcerr_weakauth.3nsl \ + svcfd_create.3nsl \ + svcraw_create.3nsl \ + svctcp_create.3nsl \ + svcudp_bufcreate.3nsl \ + svcudp_create.3nsl \ + taddr2uaddr.3nsl \ + uaddr2taddr.3nsl \ + undial.3nsl \ + user2netname.3nsl \ + xdr_accepted_reply.3nsl \ + xdr_array.3nsl \ + xdr_authsys_parms.3nsl \ + xdr_authunix_parms.3nsl \ + xdr_bool.3nsl \ + xdr_bytes.3nsl \ + xdr_callhdr.3nsl \ + xdr_callmsg.3nsl \ + xdr_char.3nsl \ + xdr_control.3nsl \ + xdr_destroy.3nsl \ + xdr_double.3nsl \ + xdr_enum.3nsl \ + xdr_float.3nsl \ + xdr_free.3nsl \ + xdr_getpos.3nsl \ + xdr_hyper.3nsl \ + xdr_inline.3nsl \ + xdr_int.3nsl \ + xdr_long.3nsl \ + xdr_longlong_t.3nsl \ + xdr_opaque.3nsl \ + xdr_opaque_auth.3nsl \ + xdr_pointer.3nsl \ + xdr_quadruple.3nsl \ + xdr_reference.3nsl \ + xdr_rejected_reply.3nsl \ + xdr_replymsg.3nsl \ + xdr_setpos.3nsl \ + xdr_short.3nsl \ + xdr_sizeof.3nsl \ + xdr_string.3nsl \ + xdr_u_char.3nsl \ + xdr_u_hyper.3nsl \ + xdr_u_int.3nsl \ + xdr_u_long.3nsl \ + xdr_u_longlong_t.3nsl \ + xdr_u_short.3nsl \ + xdr_union.3nsl \ + xdr_vector.3nsl \ + xdr_void.3nsl \ + xdr_wrapstring.3nsl \ + xdrmem_create.3nsl \ + xdrrec_create.3nsl \ + xdrrec_endofrecord.3nsl \ + xdrrec_eof.3nsl \ + xdrrec_readbytes.3nsl \ + xdrrec_skiprecord.3nsl \ + xdrstdio_create.3nsl \ + xprt_register.3nsl \ + xprt_unregister.3nsl \ + yp_all.3nsl \ + yp_bind.3nsl \ + yp_first.3nsl \ + yp_get_default_domain.3nsl \ + yp_master.3nsl \ + yp_match.3nsl \ + yp_next.3nsl \ + yp_order.3nsl \ + yp_unbind.3nsl \ + yperr_string.3nsl \ + ypprot_err.3nsl + +MANFILES += $(MANSOFILES) + +undial.3nsl := SOSRC = man3nsl/dial.3nsl + +endhostent.3nsl := SOSRC = man3nsl/gethostbyname.3nsl +gethostbyaddr.3nsl := SOSRC = man3nsl/gethostbyname.3nsl +gethostbyaddr_r.3nsl := SOSRC = man3nsl/gethostbyname.3nsl +gethostbyname_r.3nsl := SOSRC = man3nsl/gethostbyname.3nsl +gethostent.3nsl := SOSRC = man3nsl/gethostbyname.3nsl +gethostent_r.3nsl := SOSRC = man3nsl/gethostbyname.3nsl +sethostent.3nsl := SOSRC = man3nsl/gethostbyname.3nsl + +freeipsecalgent.3nsl := SOSRC = man3nsl/getipsecalgbyname.3nsl +getipsecalgbynum.3nsl := SOSRC = man3nsl/getipsecalgbyname.3nsl + +getipsecprotobynum.3nsl := SOSRC = man3nsl/getipsecprotobyname.3nsl + +endnetconfig.3nsl := SOSRC = man3nsl/getnetconfig.3nsl +freenetconfigent.3nsl := SOSRC = man3nsl/getnetconfig.3nsl +getnetconfigent.3nsl := SOSRC = man3nsl/getnetconfig.3nsl +nc_perror.3nsl := SOSRC = man3nsl/getnetconfig.3nsl +nc_sperror.3nsl := SOSRC = man3nsl/getnetconfig.3nsl +setnetconfig.3nsl := SOSRC = man3nsl/getnetconfig.3nsl + +endnetpath.3nsl := SOSRC = man3nsl/getnetpath.3nsl +setnetpath.3nsl := SOSRC = man3nsl/getnetpath.3nsl + +getsecretkey.3nsl := SOSRC = man3nsl/getpublickey.3nsl +publickey.3nsl := SOSRC = man3nsl/getpublickey.3nsl + +endrpcent.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl +getrpcbyname_r.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl +getrpcbynumber.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl +getrpcbynumber_r.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl +getrpcent.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl +getrpcent_r.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl +setrpcent.3nsl := SOSRC = man3nsl/getrpcbyname.3nsl + +netdir_free.3nsl := SOSRC = man3nsl/netdir.3nsl +netdir_getbyaddr.3nsl := SOSRC = man3nsl/netdir.3nsl +netdir_getbyname.3nsl := SOSRC = man3nsl/netdir.3nsl +netdir_mergeaddr.3nsl := SOSRC = man3nsl/netdir.3nsl +netdir_options.3nsl := SOSRC = man3nsl/netdir.3nsl +netdir_perror.3nsl := SOSRC = man3nsl/netdir.3nsl +netdir_sperror.3nsl := SOSRC = man3nsl/netdir.3nsl +taddr2uaddr.3nsl := SOSRC = man3nsl/netdir.3nsl +uaddr2taddr.3nsl := SOSRC = man3nsl/netdir.3nsl + +auth_destroy.3nsl := SOSRC = man3nsl/rpc_clnt_auth.3nsl +authnone_create.3nsl := SOSRC = man3nsl/rpc_clnt_auth.3nsl +authsys_create.3nsl := SOSRC = man3nsl/rpc_clnt_auth.3nsl +authsys_create_default.3nsl := SOSRC = man3nsl/rpc_clnt_auth.3nsl + +clnt_call.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_freeres.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_geterr.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_perrno.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_perror.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_send.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_sperrno.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +clnt_sperror.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +rpc_broadcast.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +rpc_broadcast_exp.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl +rpc_call.3nsl := SOSRC = man3nsl/rpc_clnt_calls.3nsl + +clnt_control.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_create_timed.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_create_vers.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_create_vers_timed.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_destroy.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_dg_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_door_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_pcreateerror.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_raw_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_spcreateerror.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_tli_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_tp_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_tp_create_timed.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +clnt_vc_create.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl +rpc_createerr.3nsl := SOSRC = man3nsl/rpc_clnt_create.3nsl + +rpc_gss_get_mech_info.3nsl := SOSRC = man3nsl/rpc_gss_get_mechanisms.3nsl +rpc_gss_get_versions.3nsl := SOSRC = man3nsl/rpc_gss_get_mechanisms.3nsl +rpc_gss_is_installed.3nsl := SOSRC = man3nsl/rpc_gss_get_mechanisms.3nsl + +rpc_gss_svc_max_data_length.3nsl := SOSRC = man3nsl/rpc_gss_max_data_length.3nsl + +rpc_gss_qop_to_num.3nsl := SOSRC = man3nsl/rpc_gss_mech_to_oid.3nsl + +authdes_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +authunix_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +authunix_create_default.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +callrpc.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +clnt_broadcast.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +clntraw_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +clnttcp_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +clntudp_bufcreate.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +clntudp_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +get_myaddress.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +getrpcport.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +pmap_getmaps.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +pmap_getport.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +pmap_rmtcall.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +pmap_set.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +pmap_unset.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +registerrpc.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svc_fds.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svc_getcaller.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svc_getreq.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svc_register.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svc_unregister.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svcfd_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svcraw_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svctcp_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svcudp_bufcreate.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +svcudp_create.3nsl := SOSRC = man3nsl/rpc_soc.3nsl +xdr_authunix_parms.3nsl := SOSRC = man3nsl/rpc_soc.3nsl + +svc_dg_enablecache.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_done.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_exit.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_fd_negotiate_ucred.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_fdset.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_freeargs.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_getargs.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_getcallerucred.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_getreq_common.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_getreq_poll.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_getreqset.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_getrpccaller.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_max_pollfd.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_pollfd.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_run.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl +svc_sendreply.3nsl := SOSRC = man3nsl/rpc_svc_calls.3nsl + +svc_control.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_destroy.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_dg_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_door_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_fd_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_raw_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_tli_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_tp_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl +svc_vc_create.3nsl := SOSRC = man3nsl/rpc_svc_create.3nsl + +svcerr_auth.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl +svcerr_decode.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl +svcerr_noproc.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl +svcerr_noprog.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl +svcerr_progvers.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl +svcerr_systemerr.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl +svcerr_weakauth.3nsl := SOSRC = man3nsl/rpc_svc_err.3nsl + +svc_add_input.3nsl := SOSRC = man3nsl/rpc_svc_input.3nsl +svc_remove_input.3nsl := SOSRC = man3nsl/rpc_svc_input.3nsl + +rpc_reg.3nsl := SOSRC = man3nsl/rpc_svc_reg.3nsl +svc_auth_reg.3nsl := SOSRC = man3nsl/rpc_svc_reg.3nsl +svc_reg.3nsl := SOSRC = man3nsl/rpc_svc_reg.3nsl +svc_unreg.3nsl := SOSRC = man3nsl/rpc_svc_reg.3nsl +xprt_register.3nsl := SOSRC = man3nsl/rpc_svc_reg.3nsl +xprt_unregister.3nsl := SOSRC = man3nsl/rpc_svc_reg.3nsl + +xdr_accepted_reply.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl +xdr_authsys_parms.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl +xdr_callhdr.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl +xdr_callmsg.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl +xdr_opaque_auth.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl +xdr_rejected_reply.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl +xdr_replymsg.3nsl := SOSRC = man3nsl/rpc_xdr.3nsl + +rpcb_getaddr.3nsl := SOSRC = man3nsl/rpcbind.3nsl +rpcb_getmaps.3nsl := SOSRC = man3nsl/rpcbind.3nsl +rpcb_gettime.3nsl := SOSRC = man3nsl/rpcbind.3nsl +rpcb_rmtcall.3nsl := SOSRC = man3nsl/rpcbind.3nsl +rpcb_set.3nsl := SOSRC = man3nsl/rpcbind.3nsl +rpcb_unset.3nsl := SOSRC = man3nsl/rpcbind.3nsl + +authdes_getucred.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +authdes_seccreate.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +getnetname.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +host2netname.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +key_decryptsession.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +key_encryptsession.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +key_gendes.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +key_secretkey_is_set.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +key_setsecret.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +netname2host.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +netname2user.3nsl := SOSRC = man3nsl/secure_rpc.3nsl +user2netname.3nsl := SOSRC = man3nsl/secure_rpc.3nsl + +xdr_control.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdr_getpos.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdr_inline.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdr_setpos.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdr_sizeof.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdrrec_endofrecord.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdrrec_eof.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdrrec_readbytes.3nsl := SOSRC = man3nsl/xdr_admin.3nsl +xdrrec_skiprecord.3nsl := SOSRC = man3nsl/xdr_admin.3nsl + +xdr_array.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_bytes.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_opaque.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_pointer.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_reference.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_string.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_union.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_vector.3nsl := SOSRC = man3nsl/xdr_complex.3nsl +xdr_wrapstring.3nsl := SOSRC = man3nsl/xdr_complex.3nsl + +xdr_destroy.3nsl := SOSRC = man3nsl/xdr_create.3nsl +xdrmem_create.3nsl := SOSRC = man3nsl/xdr_create.3nsl +xdrrec_create.3nsl := SOSRC = man3nsl/xdr_create.3nsl +xdrstdio_create.3nsl := SOSRC = man3nsl/xdr_create.3nsl + +xdr_bool.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_char.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_double.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_enum.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_float.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_free.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_hyper.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_int.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_long.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_longlong_t.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_quadruple.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_short.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_u_char.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_u_hyper.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_u_int.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_u_long.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_u_longlong_t.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_u_short.3nsl := SOSRC = man3nsl/xdr_simple.3nsl +xdr_void.3nsl := SOSRC = man3nsl/xdr_simple.3nsl + +yp_all.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_bind.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_first.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_get_default_domain.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_master.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_match.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_next.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_order.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yp_unbind.3nsl := SOSRC = man3nsl/ypclnt.3nsl +yperr_string.3nsl := SOSRC = man3nsl/ypclnt.3nsl +ypprot_err.3nsl := SOSRC = man3nsl/ypclnt.3nsl + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man3nsl/dial.3nsl b/usr/src/man/man3nsl/dial.3nsl new file mode 100644 index 0000000000..5cfa230e6c --- /dev/null +++ b/usr/src/man/man3nsl/dial.3nsl @@ -0,0 +1,197 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dial 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +dial, undial \- establish an outgoing terminal line connection +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR... ] +#include <dial.h> + +\fBint\fR \fBdial\fR(\fBCALL\fR \fIcall\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBundial\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdial()\fR function returns a file-descriptor for a terminal line open +for read/write. The argument to \fBdial()\fR is a \fBCALL\fR structure (defined +in the header <\fBdial.h\fR>). +.sp +.LP +When finished with the terminal line, the calling program must invoke +\fBundial()\fR to release the semaphore that has been set during the allocation +of the terminal device. +.sp +.LP +\fBCALL\fR is defined in the header <\fBdial.h\fR> and has the following +members: +.sp +.in +2 +.nf +struct termio *attr; /* pointer to termio attribute struct */ +int baud; /* transmission data rate */ +int speed; /* 212A modem: low=300, high=1200 */ +char *line; /* device name for out-going line */ +char *telno; /* pointer to tel-no digits string */ +int modem; /* specify modem control for direct lines */ +char *device; /* unused */ +int dev_len; /* unused */ +.fi +.in -2 + +.sp +.LP +The \fBCALL\fR element \fBspeed\fR is intended only for use with an outgoing +dialed call, in which case its value should be the desired transmission baud +rate. The \fBCALL\fR element \fBbaud\fR is no longer used. +.sp +.LP +If the desired terminal line is a direct line, a string pointer to its +device-name should be placed in the \fBline\fR element in the \fBCALL\fR +structure. Legal values for such terminal device names are kept in the +\fBDevices\fR file. In this case, the value of the \fBbaud\fR element should be +set to -1. This value will cause \fBdial\fR to determine the correct value from +the \fB<Devices>\fR file. +.sp +.LP +The \fBtelno\fR element is for a pointer to a character string representing the +telephone number to be dialed. Such numbers may consist only of these +characters: +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +0-9dial 0-9 +*dail * +#dail # +=wait for secondary dial tone +-delay for approximately 4 seconds +.TE + +.sp +.LP +The \fBCALL\fR element \fBmodem\fR is used to specify modem control for direct +lines. This element should be non-zero if modem control is required. The +\fBCALL\fR element \fBattr\fR is a pointer to a \fBtermio\fR structure, as +defined in the header \fB<termio.h>\fR\&. A \fINULL\fR value for this pointer +element may be passed to the \fBdial\fR function, but if such a structure is +included, the elements specified in it will be set for the outgoing terminal +line before the connection is established. This setting is often important for +certain attributes such as parity and baud-rate. +.sp +.LP +The \fBCALL\fR elements \fBdevice\fR and \fBdev_len\fR are no longer used. They +are retained in the \fBCALL\fR structure for compatibility reasons. +.SH RETURN VALUES +.sp +.LP +On failure, a negative value indicating the reason for the failure will be +returned. Mnemonics for these negative indices as listed here are defined in +the header <\fBdial.h\fR>. +.sp +.in +2 +.nf +INTRPT \(mi1 /* interrupt occurred */ +D_HUNG \(mi2 /* dialer hung (no return from write) */ +NO_ANS \(mi3 /* no answer within 10 seconds */ +ILL_BD \(mi4 /* illegal baud-rate */ +A_PROB \(mi5 /* acu problem (open(\|) failure) */ +L_PROB \(mi6 /* line problem (open(\|) failure) */ +NO_Ldv \(mi7 /* can't open Devices file */ +DV_NT_A \(mi8 /* requested device not available */ +DV_NT_K \(mi9 /* requested device not known */ +NO_BD_A \(mi10 /* no device available at requested baud */ +NO_BD_K \(mi11 /* no device known at requested baud */ +DV_NT_E \(mi12 /* requested speed does not match */ +BAD_SYS \(mi13 /* system not in Systems file*/ +.fi +.in -2 + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/uucp/Devices\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/uucp/Systems\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/spool/uucp/LCK..\fR\fItty-device\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBuucp\fR(1C), \fBalarm\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBattributes\fR(5), \fBtermio\fR(7I) +.SH NOTES +.sp +.LP +Including the header <\fBdial.h\fR> automatically includes the header +\fB<termio.h>\fR\&. An \fBalarm\fR(2) system call for 3600 seconds is made (and +caught) within the \fBdial\fR module for the purpose of ``touching'' the +\fBLCK..\fR file and constitutes the device allocation semaphore for the +terminal device. Otherwise, \fBuucp\fR(1C) may simply delete the \fBLCK..\fR +entry on its 90-minute clean-up rounds. The alarm may go off while the user +program is in a \fBread\fR(2) or \fBwrite\fR(2) function, causing an apparent +error return. If the user program expects to be around for an hour or more, +error returns from \fBread()\fRs should be checked for \fB(errno==EINTR)\fR, +and the \fBread()\fR possibly reissued. +.sp +.LP +This interface is unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/doconfig.3nsl b/usr/src/man/man3nsl/doconfig.3nsl new file mode 100644 index 0000000000..561f1e6580 --- /dev/null +++ b/usr/src/man/man3nsl/doconfig.3nsl @@ -0,0 +1,181 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH doconfig 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +doconfig \- execute a configuration script +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lnsl\fR [ \fIlibrary\fR ... ] +# include <sac.h> + + + +\fBint\fR \fBdoconfig\fR(\fBint\fR \fIfildes\fR, \fBchar *\fR\fIscript\fR, \fBlong\fR \fIrflag\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBdoconfig()\fR is a Service Access Facility library function that interprets +the configuration scripts contained in the files +\fB</etc/saf/\fR\fIpmtag\fR\fB/_config>\fR, \fB</etc/saf/_sysconfig>\fR, and +\fB</etc/saf/\fR\fIpmtag\fR/\fIsvctag>\fR, where \fIpmtag\fR specifies the tag +associated with the port monitor, and \fIsvctag\fR specifies the service tag +associated with a given service. See \fBpmadm\fR(1M) and \fBsacadm\fR(1M). +.sp +.LP +\fBscript\fR is the name of the configuration script; \fIfildes\fR is a file +descriptor that designates the stream to which stream manipulation operations +are to be applied; \fIrflag\fR is a bitmask that indicates the mode in which +\fBscript\fR is to be interpreted. If \fIrflag\fR is zero, all commands in the +configuration script are eligible to be interpreted. If \fIrflag\fR has the +\fBNOASSIGN\fR bit set, the \fBassign\fR command is considered illegal and will +generate an error return. If \fIrflag\fR has the \fBNORUN\fR bit set, the +\fBrun\fR and \fBrunwait\fR commands are considered illegal and will generate +error returns. +.sp +.LP +The configuration language in which \fBscript\fR is written consists of a +sequence of commands, each of which is interpreted separately. The following +reserved keywords are defined: \fBassign\fR, \fBpush\fR, \fBpop\fR, +\fBrunwait\fR, and \fBrun\fR. The comment character is \fB#\fR; when a \fB#\fR +occurs on a line, everything from that point to the end of the line is ignored. +Blank lines are not significant. No line in a command script may exceed 1024 +characters. +.sp +.ne 2 +.mk +.na +\fB\fBassign\fR \fIvariable\fR=\fIvalue\fR\fR +.ad +.sp .6 +.RS 4n +Used to define environment variables. \fIvariable\fR is the name of the +environment variable and \fIvalue\fR is the value to be assigned to it. The +value assigned must be a string constant; no form of parameter substitution is +available. \fIvalue\fR may be quoted. The quoting rules are those used by the +shell for defining environment variables. \fBassign\fR will fail if space +cannot be allocated for the new variable or if any part of the specification is +invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpush\fR \fImodule1\fR[, \fImodule2\fR, \fImodule3\fR, . . .]\fR +.ad +.sp .6 +.RS 4n +Used to push STREAMS modules onto the stream designated by \fIfildes\fR. +\fImodule1\fR is the name of the first module to be pushed, \fImodule2\fR is +the name of the second module to be pushed, etc. The command will fail if any +of the named modules cannot be pushed. If a module cannot be pushed, the +subsequent modules on the same command line will be ignored and modules that +have already been pushed will be popped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpop\fR [\fImodule\fR]\fR +.ad +.sp .6 +.RS 4n +Used to pop STREAMS modules off the designated stream. If \fBpop\fR is invoked +with no arguments, the top module on the stream is popped. If an argument is +given, modules will be popped one at a time until the named module is at the +top of the stream. If the named module is not on the designated stream, the +stream is left as it was and the command fails. If \fImodule\fR is the special +keyword ALL, then all modules on the stream will be popped. Note that only +modules above the topmost driver are affected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrunwait\fR \fBcommand\fR\fR +.ad +.sp .6 +.RS 4n +The \fBrunwait\fR command runs a command and waits for it to complete. +\fBcommand\fR is the pathname of the command to be run. The command is run with +\fB/usr/bin/sh \fR\fB-c \fR prepended to it; shell scripts may thus be executed +from configuration scripts. The \fBrunwait\fR command will fail if +\fBcommand\fR cannot be found or cannot be executed, or if \fBcommand\fR exits +with a non-zero status. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrun\fR \fBcommand\fR\fR +.ad +.sp .6 +.RS 4n +The \fBrun\fR command is identical to \fBrunwait\fR except that it does not +wait for \fBcommand\fR to complete. \fBcommand\fR is the pathname of the +command to be run. \fBrun\fR will not fail unless it is unable to create a +child process to execute the command. +.RE + +.sp +.LP +Although they are syntactically indistinguishable, some of the commands +available to \fBrun\fR and \fBrunwait\fR are interpreter built-in commands. +Interpreter built-ins are used when it is necessary to alter the state of a +process within the context of that process. The \fBdoconfig()\fR interpreter +built-in commands are similar to the shell special commands and, like these, +they do not spawn another process for execution. See \fBsh\fR(1). The built-in +commands are: +.sp +.in +2 +.nf +\fBcd +ulimit +umask\fR +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +\fBdoconfig()\fR returns \fB0\fR if the script was interpreted successfully. If +a command in the script fails, the interpretation of the script ceases at that +point and a positive number is returned; this number indicates which line in +the script failed. If a system error occurs, a value of \fB\(mi1\fR is +returned. When a script fails, the process whose environment was being +established should \fInot\fR be started. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsh\fR(1), \fBpmadm\fR(1M), \fBsacadm\fR(1M), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +This interface is unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/gethostbyname.3nsl b/usr/src/man/man3nsl/gethostbyname.3nsl new file mode 100644 index 0000000000..3e9d4a44d3 --- /dev/null +++ b/usr/src/man/man3nsl/gethostbyname.3nsl @@ -0,0 +1,418 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gethostbyname 3NSL "24 Aug 2007" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethostent, +gethostent_r, sethostent, endhostent \- get network host entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR... ] +#include <netdb.h> + +\fBstruct hostent *\fR\fBgethostbyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostbyname_r\fR(\fBconst char *\fR\fIname\fR, + \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR, + \fBint *\fR\fIh_errnop\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostbyaddr\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlen\fR, + \fBint\fR \fItype\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostbyaddr_r\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlength\fR, + \fBint\fR \fItype\fR, \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostent_r\fR(\fBstruct hostent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR); +.fi + +.LP +.nf +\fBint\fR \fBsethostent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.LP +.nf +\fBint\fR \fBendhostent\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain entries describing hosts. An entry can come +from any of the sources for \fBhosts\fR specified in the +\fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4). These functions have +been superseded by \fBgetipnodebyname\fR(3SOCKET), +\fBgetipnodebyaddr\fR(3SOCKET), and \fBgetaddrinfo\fR(3SOCKET), which provide +greater portability to applications when multithreading is performed or +technologies such as IPv6 are used. For example, the functions described in the +following cannot be used with applications targeted to work with IPv6. +.sp +.LP +The \fBgethostbyname()\fR function searches for information for a host with the +hostname specified by the character-string parameter \fIname\fR. +.sp +.LP +The \fBgethostbyaddr()\fR function searches for information for a host with a +given host address. The parameter \fBtype\fR specifies the family of the +address. This should be one of the address families defined in +\fB<sys/socket.h>\fR\&. See the \fBNOTES\fR section for more information. Also +see the \fBEXAMPLES\fR section for information on how to convert an Internet +\fBIP\fR address notation that is separated by periods (.) into an \fIaddr\fR +parameter. The parameter \fIlen\fR specifies the length of the buffer indicated +by \fIaddr\fR. +.sp +.LP +All addresses are returned in network order. In order to interpret the +addresses, \fBbyteorder\fR(3SOCKET) must be used for byte order conversion. +.sp +.LP +The \fBsethostent()\fR, \fBgethostent()\fR, and \fBendhostent()\fR functions +are used to enumerate host entries from the database. +.sp +.LP +The \fBsethostent()\fR function sets or resets the enumeration to the beginning +of the set of host entries. This function should be called before the first +call to \fBgethostent()\fR. Calls to \fBgethostbyname()\fR and +\fBgethostbyaddr()\fR leave the enumeration position in an indeterminate state. +If the \fIstayopen\fR flag is non-zero, the system can keep allocated resources +such as open file descriptors until a subsequent call to \fBendhostent()\fR. +.sp +.LP +Successive calls to the \fBgethostent()\fR function return either successive +entries or \fINULL,\fR indicating the end of the enumeration. +.sp +.LP +The \fBendhostent()\fR function can be called to indicate that the caller +expects to do no further host entry retrieval operations; the system can then +deallocate resources it was using. It is still allowed, but possibly less +efficient, for the process to call more host retrieval functions after calling +\fBendhostent()\fR. +.SS "Reentrant Interfaces" +.sp +.LP +The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR +functions use static storage that is reused in each call, making these +functions unsafe for use in multithreaded applications. +.sp +.LP +The \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR +functions provide reentrant interfaces for these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces, +however, use buffers supplied by the caller to store returned results and the +interfaces are safe for use in both single-threaded and multithreaded +applications. +.sp +.LP +Each reentrant interface takes the same parameters as its non-reentrant +counterpart, as well as the following additional parameters. The parameter +\fIresult\fR must be a pointer to a \fBstruct hostent\fR structure allocated by +the caller. On successful completion, the function returns the host entry in +this structure. The parameter \fIbuffer\fR must be a pointer to a buffer +supplied by the caller. This buffer is used as storage space for the host data. +All of the pointers within the returned \fBstruct hostent\fR \fIresult\fR point +to data stored within this buffer. See the \fBRETURN VALUES\fR section for more +information. The buffer must be large enough to hold all of the data associated +with the host entry. The parameter \fIbuflen\fR should give the size in bytes +of the buffer indicated by \fIbuffer\fR. The parameter \fIh_errnop\fR should be +a pointer to an integer. An integer error status value is stored there on +certain error conditions. See the \fBERRORS\fR section for more information. +.sp +.LP +For enumeration in multithreaded applications, the position within the +enumeration is a process-wide property shared by all threads. The +\fBsethostent()\fR function can be used in a multithreaded application but +resets the enumeration position for all threads. If multiple threads interleave +calls to \fBgethostent_r()\fR, the threads will enumerate disjoint subsets of +the host database. +.sp +.LP +Like their non-reentrant counterparts, \fBgethostbyname_r()\fR and +\fBgethostbyaddr_r()\fR leave the enumeration position in an indeterminate +state. +.SH RETURN VALUES +.sp +.LP +Host entries are represented by the \fBstruct hostent\fR structure defined in +\fB<netdb.h>\fR: +.sp +.in +2 +.nf +struct hostent { + char *h_name; /* canonical name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses */ +}; +.fi +.in -2 + +.sp +.LP +See the \fBEXAMPLES\fR section for information about how to retrieve a ``.'' +separated Internet \fBIP\fR address string from the \fIh_addr_list\fR field of +\fBstruct hostent\fR. +.sp +.LP +The \fBgethostbyname()\fR, \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and +\fBgethostbyaddr_r()\fR functions each return a pointer to a \fBstruct +hostent\fR if they successfully locate the requested entry; otherwise they +return \fINULL\fR. +.sp +.LP +The \fBgethostent()\fR and \fBgethostent_r()\fR functions each return a pointer +to a \fBstruct hostent\fR if they successfully enumerate an entry; otherwise +they return \fINULL\fR, indicating the end of the enumeration. +.sp +.LP +The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR +functions use static storage, so returned data must be copied before a +subsequent call to any of these functions if the data is to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgethostbyname_r()\fR, +\fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR is not \fINULL\fR, it is +always equal to the \fIresult\fR pointer that was supplied by the caller. +.sp +.LP +The \fBsethostent()\fR and \fBendhostent()\fR functions return \fB0\fR on +success. +.SH ERRORS +.sp +.LP +The reentrant functions \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and +\fBgethostent_r()\fR will return \fINULL\fR and set \fIerrno\fR to \fBERANGE\fR +if the length of the buffer supplied by caller is not large enough to store the +result. See \fBIntro\fR(2) for the proper usage and interpretation of +\fBerrno\fR in multithreaded applications. +.sp +.LP +The reentrant functions \fBgethostbyname_r()\fR and \fBgethostbyaddr_r()\fR set +the integer pointed to by \fIh_errnop\fR to one of these values in case of +error. +.sp +.LP +On failures, the non-reentrant functions \fBgethostbyname()\fR and +\fBgethostbyaddr()\fR set a global integer \fIh_errno\fR to indicate one of +these error codes (defined in \fB<netdb.h>\fR): \fBHOST_NOT_FOUND\fR, +\fBTRY_AGAIN\fR, \fBNO_RECOVERY\fR, \fBNO_DATA\fR, and \fBNO_ADDRESS\fR. +.sp +.LP +If a resolver is provided with a malformed address, or if any other error +occurs before \fBgethostbyname()\fR is resolved, then \fBgethostbyname()\fR +returns an internal error with a value of \(mi1. +.sp +.LP +The \fBgethostbyname()\fR function will set \fIh_errno\fR to +\fBNETDB_INTERNAL\fR when it returns a \fINULL\fR value. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBgethostbyaddr()\fR +.sp +.LP +Here is a sample program that gets the canonical name, aliases, and ``.'' +separated Internet \fBIP\fR addresses for a given ``.'' separated \fBIP\fR +address: + +.sp +.in +2 +.nf +#include <stdio.h> +#include <stdlib.h +#include <string.h> +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/in.h> +#include <arpa/inet.h> +#include <netdb.h> +int main(int argc, const char **argv) +{ + in_addr_t addr; + struct hostent *hp; + char **p; + if (argc != 2) { + (void) printf("usage: %s IP-address\en", argv[0]); + exit (1); + } + if ((int)(addr = inet_addr(argv[1])) == -1) { + (void) printf("IP-address must be of the form a.b.c.d\en"); + exit (2); + } + hp = gethostbyaddr((char *)&addr, 4, AF_INET); + if (hp == NULL) { + (void) printf("host information for %s not found\en", argv[1]); + exit (3); + } + for (p = hp->h_addr_list; *p != 0; p++) { + struct in_addr in; + char **q; + (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr)); + (void) printf("%s\t%s", inet_ntoa(in), hp\(mi>h_name); + for (q = hp->h_aliases; *q != 0; q++) + (void) printf(" %s", *q); + (void) putchar('\n'); + } + exit (0); +} +.fi +.in -2 + +.sp +.LP +Note that the preceding sample program is unsafe for use in multithreaded +applications. + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/hosts\fR\fR +.ad +.RS 22n +.rt +hosts file that associates the names of hosts with their Internet Protocol (IP) +addresses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/netconfig\fR\fR +.ad +.RS 22n +.rt +network configuration database +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt +configuration file for the name service switch +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelT{ +See \fBReentrant Interfaces\fR in the \fBDESCRIPTION\fR section. +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET), +\fBnetdb.h\fR(3HEAD), \fBnetdir\fR(3NSL), \fBhosts\fR(4), \fBnetconfig\fR(4), +\fBnss\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +The reentrant interfaces \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and +\fBgethostent_r()\fR are included in this release on an uncommitted basis only +and are subject to change or removal in future minor releases. +.SH NOTES +.sp +.LP +To ensure that they all return consistent results, \fBgethostbyname()\fR, +\fBgethostbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms +of the same internal library function. This function obtains the system-wide +source lookup policy based on the \fBinet\fR family entries in +\fBnetconfig\fR(4) and the \fBhosts:\fR entry in \fBnsswitch.conf\fR(4). +Similarly, \fBgethostbyaddr()\fR, \fBgethostbyaddr_r()\fR, and +\fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library +function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-'' +in the last column for \fBnametoaddr\fR libraries, then the entry for +\fBhosts\fR in \fBnsswitch.conf\fR will be used; \fBnametoaddr\fR libraries in +that column will be used, and \fBnsswitch.conf\fR will not be consulted. +.sp +.LP +There is no analogue of \fBgethostent()\fR and \fBgethostent_r()\fR in the +netdir functions, so these enumeration functions go straight to the \fBhosts\fR +entry in \fBnsswitch.conf\fR. Thus enumeration can return results from a +different source than that used by \fBgethostbyname()\fR, +\fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyaddr_r()\fR. +.sp +.LP +All the functions that return a \fBstruct hostent\fR must always return the +\fIcanonical name\fR in the \fIh_name\fR field. This name, by definition, is +the well-known and official hostname shared between all aliases and all +addresses. The underlying source that satisfies the request determines the +mapping of the input name or address into the set of names and addresses in +\fBhostent\fR. Different sources might do that in different ways. If there is +more than one alias and more than one address in \fBhostent\fR, no pairing is +implied between them. +.sp +.LP +The system attempts to put those addresses that are on the same subnet as the +caller before addresses that are on different subnets. However, if address +sorting is disabled by setting \fBSORT_ADDRS\fR to FALSE in the +\fB/etc/default/nss\fR file, the system does not put the local subnet addresses +first. See \fBnss\fR(4) for more information. +.sp +.LP +When compiling multithreaded applications, see \fBIntro\fR(3), \fBMULTITHREADED +APPLICATIONS\fR, for information about the use of the \fB_REENTRANT\fR flag. +.sp +.LP +Use of the enumeration interfaces \fBgethostent()\fR and \fBgethostent_r()\fR +is discouraged; enumeration might not be supported for all database sources. +The semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4). +.sp +.LP +The current implementations of these functions only return or accept addresses +for the Internet address family (type \fBAF_INET\fR). +.sp +.LP +The form for an address of type \fBAF_INET\fR is a \fBstruct in_addr\fR defined +in <\fBnetinet/in.h\fR>. The functions described in \fBinet\fR(3SOCKET), and +illustrated in the \fBEXAMPLES\fR section, are helpful in constructing and +manipulating addresses in this form. diff --git a/usr/src/man/man3nsl/getipsecalgbyname.3nsl b/usr/src/man/man3nsl/getipsecalgbyname.3nsl new file mode 100644 index 0000000000..ca4c7c9b04 --- /dev/null +++ b/usr/src/man/man3nsl/getipsecalgbyname.3nsl @@ -0,0 +1,216 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getipsecalgbyname 3NSL "20 Aug 2003" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +getipsecalgbyname, getipsecalgbynum, freeipsecalgent \- query algorithm mapping +entries +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-flag \&.\|.\|.\fR \fIfile\fR \&.\|.\|.\fB-l\fRnsl [\fB -library \&.\|.\|. \fR] +#include <netdb.h> + + + +\fBstruct ipsecalgent *\fR\fBgetipsecalgbyname\fR + (\fBconst char *\fR\fIalg_name\fR, \fBint\fR \fIprotocol_num\fR, \fBint *\fR\fIerrnop\fR +.fi + +.LP +.nf +\fBstruct ipsecalgent *\fR\fBgetipsecalgbynum\fR(\fBint\fR \fIalg_num\fR, \fBint\fR \fIprotocol_num\fR, + \fBint *\fR\fIerrnop\fR +.fi + +.LP +.nf +\fBvoid\fR \fBfreeipsecalgent\fR(\fBstruct ipsecalgent *\fR\fIptr\fR +.fi + +.SH DESCRIPTION +.sp +.LP +Use the \fBgetipsecalgbyname()\fR, \fBgetipsecalgbynum()\fR, +\fBfreeipsecalgent()\fR functions to obtain the IPsec algorithm mappings that +are defined by \fBipsecalgs\fR(1M). The IPsec algorithms and associated +protocol name spaces are defined by \fIRFC 2407\fR. +.sp +.LP +\fBgetipsecalgbyname()\fR and \fBgetipsecalgbynum()\fR return a structure that +describes the algorithm entry found. This structure is described in the +\fBRETURN VALUES\fR section below. +.sp +.LP +\fBfreeipsecalgent()\fR must be used by the caller to free the structures +returned by \fBgetipsecalgbyname()\fR and \fBgetipsecalgbynum()\fR when they +are no longer needed. +.sp +.LP +Both \fBgetipsecalgbyname()\fR and \fBgetipsecalgbynum()\fR take as parameter +the protocol identifier in which the algorithm is defined. See +\fBgetipsecprotobyname\fR(3NSL) and \fBgetipsecprotobyname\fR(3NSL). +.sp +.LP +The following protocol numbers are pre-defined: +.sp +.ne 2 +.mk +.na +\fB\fBIPSEC_PROTO_ESP\fR\fR +.ad +.RS 19n +.rt +Defines the encryption algorithms (transforms) that can be used by IPsec to +provide data confidentiality. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIPSEC_PROTO_AH\fR\fR +.ad +.RS 19n +.rt +Defines the authentication algorithms (transforms) that can be used by IPsec to +provide authentication. +.RE + +.sp +.LP +\fBgetipsecalgbyname()\fR looks up the algorithm by its name, while +\fBgetipsecalgbynum()\fR looks up the algorithm by its assigned number. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIerrnop\fR\fR +.ad +.RS 10n +.rt +A pointer to an integer used to return an error status value on certain error +conditions. See \fBERRORS\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBgetipsecalgbyname()\fR and \fBgetipsecalgbynum()\fR functions return a +pointer to the structure \fBipsecalgent_t\fR, defined in <\fBnetdb.h\fR>. If +the requested algorithm cannot be found, these functions return \fINULL\fR. +.sp +.LP +The structure \fBipsecalgent_t\fR is defined as follows: +.sp +.in +2 +.nf +typedef struct ipsecalgent { + char **a_names; /* algorithm names */ + int a_proto_num; /* protocol number */ + int a_alg_num; /* algorithm number */ + char *a_mech_name; /* mechanism name */ + int *a_block_sizes; /* supported block sizes */ + int *a_key_sizes; /* supported key sizes */ + int a_key_increment; /* key size increment */ +} ipsecalgent_t; +.fi +.in -2 + +.sp +.LP +If \fBa_key_increment\fR is non-zero, \fBa_key_sizes[0]\fR contains the default +key size for the algorithm. \fBa_key_sizes[1]\fR and \fBa_key_sizes[2]\fR +specify the smallest and biggest key sizes support by the algorithm, and +\fBa_key_increment\fR specifies the valid key size increments in that range. +.sp +.LP +If \fBa_key_increment\fR is zero, the array \fBa_key_sizes\fR contains the set +of key sizes, in bits, supported by the algorithm. The last key length in the +array is followed by an element of value \fB0\fR. The first element of this +array is used as the default key size for the algorithm. +.sp +.LP +\fBa_name\fR is an array of algorithm names, terminated by an element +containing a \fINULL\fR pointer. \fBa_name[0]\fR is the primary name for the +algorithm. +.sp +.LP +\fBa_proto_num\fR is the protocol identifer of this algorithm. \fBa_alg_num\fR +is the algorithm number. \fBa_mech_name\fR contains the mechanism name +associated with the algorithm. +.sp +.LP +\fBa_block_sizes\fR is an array containing the supported block lengths or MAC +lengths, in bytes, supported by the algorithm. The last valid value in the +array is followed by an element containing the value \fB0\fR. +.SH ERRORS +.sp +.LP +When the specified algorithm cannot be returned to the caller, +\fBgetipsecalgbynam()\fR and \fBgetipsecalgbynum()\fR return a value of +\fINULL\fR and set the integer pointed to by the \fIerrnop\fR parameter to one +of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Not enough memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +.rt +Specified algorithm not found +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Specified protocol number not found +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +MT LevelMT Safe +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBcryptoadm\fR(1M), \fBipsecalgs\fR(1M), \fBgetipsecprotobyname\fR(3NSL), +\fBgetipsecprotobyname\fR(3NSL), \fBattributes\fR(5) +.sp +.LP +Piper, D. \fIRFC 2407, The Internet IP Security Domain of Interpretation for +ISAKMP\fR. Network Working Group. November, 1998. diff --git a/usr/src/man/man3nsl/getipsecprotobyname.3nsl b/usr/src/man/man3nsl/getipsecprotobyname.3nsl new file mode 100644 index 0000000000..4c823e84e3 --- /dev/null +++ b/usr/src/man/man3nsl/getipsecprotobyname.3nsl @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getipsecprotobyname 3NSL "13 Aug 2003" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +getipsecprotobyname, getipsecprotobynum \- query IPsec protocols entries +.SH SYNOPSIS +.LP +.nf +\fBcc \fR\fB-flag \&.\|.\|.\fR \fIfile \fR\&.\|.\|.\fB-l\fRnsl [\fB -library \&.\|.\|. \fR] +#include <netdb.h> + + + +\fBint\fR \fBgetipsecprotobyname\fR(\fBconst char *\fR\fIproto_name\fR +.fi + +.LP +.nf +\fBchar *\fR\fBgetipsecprotobynum\fR(\fBint\fR \fIproto_num\fRp +.fi + +.SH DESCRIPTION +.sp +.LP +Use the \fBgetipsecprotobyname()\fR and \fBgetipsecprotobynum()\fR functions to +obtain the IPsec algorithm mappings that are defined by \fBipsecalgs\fR(1M). +You can also use the \fBgetipsecprotobyname()\fR and \fBgetipsecprotobynum()\fR +functions in conjunction with \fBgetipsecalgbyname\fR(3NSL) and +\fBgetipsecalgbynum\fR(3NSL) to obtain information about the supported IPsec +algorithms. The IPsec algorithms and associated protocol name spaces are +defined by \fIRFC 2407\fR. +.sp +.LP +\fBgetipsecprotobyname()\fR takes as an argument the name of an IPsec protocol +and returns its assigned protocol number. The character string returned by the +\fBgetipsecprotobyname()\fR function must be freed by the called when it is no +longer needed. +.sp +.LP +\fBgetipsecprotobynum()\fR takes as an argument a protocol number and returns +the corresponding protocol name. +.sp +.LP +The following protocol numbers are pre-defined: +.sp +.ne 2 +.mk +.na +\fB\fBIPSEC_PROTO_ESP\fR\fR +.ad +.RS 19n +.rt +Defines the encryption algorithms (transforms) that can be used by IPsec to +provide data confidentiality. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIPSEC_PROTO_AH\fR\fR +.ad +.RS 19n +.rt +Defines the authentication algorithms (transforms) that can be used by IPsec to +provide authentication. +.RE + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIproto_name\fR\fR +.ad +.RS 14n +.rt +A pointer to the name of an IPsec protocol. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIproto_num\fR\fR +.ad +.RS 14n +.rt +A pointer to a protocol number. conditions. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBgetipsecprotobyname()\fR function returns a protocol number upon +success, or \fB-1\fR if the protocol specified does not exist. +.sp +.LP + The \fBgetipsecprotobynum()\fR function returns a protocol name upon success, +or the \fINULL\fR value if the protocol number specified does not exist. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +MT LevelMT Safe +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBipsecalgs\fR(1M), \fBgetipsecalgbyname\fR(3NSL), +\fBgetipsecalgbyname\fR(3NSL), \fBattributes\fR(5) +.sp +.LP +Piper, D. \fIRFC 2407, The Internet IP Security Domain of Interpretation for +ISAKMP\fR. Network Working Group. November, 1998. diff --git a/usr/src/man/man3nsl/getnetconfig.3nsl b/usr/src/man/man3nsl/getnetconfig.3nsl new file mode 100644 index 0000000000..9872ff59a7 --- /dev/null +++ b/usr/src/man/man3nsl/getnetconfig.3nsl @@ -0,0 +1,155 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getnetconfig 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +getnetconfig, setnetconfig, endnetconfig, getnetconfigent, freenetconfigent, +nc_perror, nc_sperror \- get network configuration database entry +.SH SYNOPSIS +.LP +.nf +#include <netconfig.h> + + + + +\fBstruct netconfig *\fR\fBgetnetconfig\fR(\fBvoid *\fR\fIhandlep\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBsetnetconfig\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBendnetconfig\fR(\fBvoid *\fR\fIhandlep\fR); +.fi + +.LP +.nf +\fBstruct netconfig *\fR\fBgetnetconfigent\fR(\fBconst char *\fR\fInetid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfreenetconfigent\fR(\fBstruct netconfig *\fR\fInetconfigp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBnc_perror\fR(\fBconst char *\fR\fImsg\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBnc_sperror\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The library routines described on this page are part of the Network Selection +component. They provide the application access to the system network +configuration database, \fB/etc/netconfig\fR. In addition to the routines for +accessing the \fBnetconfig\fR database, Network Selection includes the +environment variable \fBNETPATH\fR (see \fBenviron\fR(5)) and the +\fBNETPATH\fR access routines described in \fBgetnetpath\fR(3NSL). +.sp +.LP +\fBgetnetconfig()\fR returns a pointer to the current entry in the +\fBnetconfig\fR database, formatted as a \fBstruct netconfig\fR. Successive +calls will return successive \fBnetconfig\fR entries in the \fBnetconfig\fR +database. \fBgetnetconfig()\fR can be used to search the entire +\fBnetconfig\fR file. \fBgetnetconfig()\fR returns \fBNULL\fR at the end of +the file. \fIhandlep\fR is the handle obtained through \fBsetnetconfig()\fR. +.sp +.LP +A call to \fBsetnetconfig()\fR has the effect of ``binding'' to or +``rewinding'' the \fBnetconfig\fR database. \fBsetnetconfig()\fR must be called +before the first call to \fBgetnetconfig()\fR and may be called at any other +time. \fBsetnetconfig()\fR need \fInot\fR be called before a call to +\fBgetnetconfigent()\fR. \fBsetnetconfig()\fR returns a unique handle to be +used by \fBgetnetconfig()\fR. +.sp +.LP +\fBendnetconfig()\fR should be called when processing is complete to release +resources for reuse. \fIhandlep\fR is the handle obtained through +\fBsetnetconfig()\fR. Programmers should be aware, however, that the last call +to \fBendnetconfig()\fR frees all memory allocated by \fBgetnetconfig()\fR for +the \fBstruct netconfig\fR data structure. \fBendnetconfig()\fR may not be +called before \fBsetnetconfig()\fR. +.sp +.LP +\fBgetnetconfigent()\fR returns a pointer to the \fBstruct netconfig\fR +structure corresponding to \fInetid\fR. It returns \fBNULL\fR if \fInetid\fR +is invalid (that is, does not name an entry in the \fBnetconfig\fR database). +.sp +.LP +\fBfreenetconfigent()\fR frees the netconfig structure pointed to by +\fInetconfigp\fR (previously returned by \fBgetnetconfigent()\fR). +.sp +.LP +\fBnc_perror()\fR prints a message to the standard error indicating why any of +the above routines failed. The message is prepended with the string \fImsg\fR +and a colon. A \fBNEWLINE\fR is appended at the end of the message. +.sp +.LP +\fBnc_sperror()\fR is similar to \fBnc_perror()\fR but instead of sending the +message to the standard error, will return a pointer to a string that contains +the error message. +.sp +.LP +\fBnc_perror()\fR and \fBnc_sperror()\fR can also be used with the +\fBNETPATH\fR access routines defined in \fBgetnetpath\fR(3NSL). +.SH RETURN VALUES +.sp +.LP +\fBsetnetconfig()\fR returns a unique handle to be used by +\fBgetnetconfig()\fR. In the case of an error, \fBsetnetconfig()\fR returns +\fBNULL\fR and \fBnc_perror()\fR or \fBnc_sperror()\fR can be used to print +the reason for failure. +.sp +.LP +\fBgetnetconfig()\fR returns a pointer to the current entry in the +\fBnetconfig()\fR database, formatted as a \fBstruct netconfig\fR. +\fBgetnetconfig()\fR returns \fBNULL\fR at the end of the file, or upon +failure. +.sp +.LP +\fBendnetconfig()\fR returns \fB0\fR on success and \fB\(mi1\fR on failure (for +example, if \fBsetnetconfig()\fR was not called previously). +.sp +.LP +On success, \fBgetnetconfigent()\fR returns a pointer to the \fBstruct\fR +\fBnetconfig\fR structure corresponding to \fInetid\fR; otherwise it returns +\fBNULL.\fR +.sp +.LP +\fBnc_sperror()\fR returns a pointer to a buffer which contains the error +message string. This buffer is overwritten on each call. In multithreaded +applications, this buffer is implemented as thread-specific data. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetnetpath\fR(3NSL), \fBnetconfig\fR(4), \fBattributes\fR(5), +\fBenviron\fR(5) diff --git a/usr/src/man/man3nsl/getnetpath.3nsl b/usr/src/man/man3nsl/getnetpath.3nsl new file mode 100644 index 0000000000..8e9dea451f --- /dev/null +++ b/usr/src/man/man3nsl/getnetpath.3nsl @@ -0,0 +1,111 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getnetpath 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +getnetpath, setnetpath, endnetpath \- get /etc/netconfig entry corresponding to +NETPATH component +.SH SYNOPSIS +.LP +.nf +#include <netconfig.h> + + + +\fBstruct netconfig *\fR\fBgetnetpath\fR(\fBvoid *\fR\fIhandlep\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBsetnetpath\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBendnetpath\fR(\fBvoid *\fR\fIhandlep\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The routines described on this page are part of the Network Selection +component. They provide the application access to the system network +configuration database, \fB/etc/netconfig\fR, as it is "filtered" by the +\fBNETPATH\fR environment variable. See \fBenviron\fR(5). See +\fBgetnetconfig\fR(3NSL) for other routines that also access the network +configuration database directly. The \fBNETPATH\fR variable is a list of +colon-separated network identifiers. +.sp +.LP +\fBgetnetpath()\fR returns a pointer to the \fBnetconfig\fR database entry +corresponding to the first valid \fBNETPATH\fR component. The \fBnetconfig\fR +entry is formatted as a \fBstruct netconfig\fR. On each subsequent call, +\fBgetnetpath()\fR returns a pointer to the \fBnetconfig\fR entry that +corresponds to the next valid \fBNETPATH\fR component. \fBgetnetpath()\fR can +thus be used to search the \fBnetconfig\fR database for all networks included +in the \fBNETPATH\fR variable. When \fBNETPATH\fR has been exhausted, +\fBgetnetpath()\fR returns NULL. +.sp +.LP +A call to \fBsetnetpath()\fR "binds" to or "rewinds" \fBNETPATH\fR. +\fBsetnetpath()\fR must be called before the first call to \fBgetnetpath()\fR +and may be called at any other time. It returns a handle that is used by +\fBgetnetpath()\fR. +.sp +.LP +\fBgetnetpath()\fR silently ignores invalid \fBNETPATH\fR components. A +\fBNETPATH\fR component is invalid if there is no corresponding entry in the +\fBnetconfig\fR database. +.sp +.LP +If the \fBNETPATH\fR variable is \fBunset\fR, \fBgetnetpath()\fR behaves as if +\fBNETPATH\fR were set to the sequence of "default" or "visible" networks in +the \fBnetconfig\fR database, in the order in which they are listed. +.sp +.LP +\fBendnetpath()\fR may be called to "unbind" from \fBNETPATH\fR when processing +is complete, releasing resources for reuse. Programmers should be aware, +however, that \fBendnetpath()\fR frees all memory allocated by +\fBgetnetpath()\fR for the \fBstruct netconfig\fR data structure. +\fBendnetpath()\fR returns \fB0\fR on success and \fB-1\fR on failure (for +example, if \fBsetnetpath()\fR was not called previously). +.SH RETURN VALUES +.sp +.LP +\fBsetnetpath()\fR returns a handle that is used by \fBgetnetpath()\fR. In case +of an error, \fBsetnetpath()\fR returns \fBNULL.\fR \fBnc_perror()\fR or +\fBnc_sperror()\fR can be used to print out the reason for failure. See +\fBgetnetconfig\fR(3NSL). +.sp +.LP +When first called, \fBgetnetpath()\fR returns a pointer to the \fBnetconfig\fR +database entry corresponding to the first valid \fBNETPATH\fR component. When +\fBNETPATH\fR has been exhausted, \fBgetnetpath()\fR returns NULL. +.sp +.LP +\fBendnetpath()\fR returns \fB0\fR on success and\fB -1 \fRon failure (for +example, if \fBsetnetpath()\fR was not called previously). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetnetconfig\fR(3NSL), \fBnetconfig\fR(4), \fBattributes\fR(5), +\fBenviron\fR(5) diff --git a/usr/src/man/man3nsl/getpublickey.3nsl b/usr/src/man/man3nsl/getpublickey.3nsl new file mode 100644 index 0000000000..9d1be8e5ff --- /dev/null +++ b/usr/src/man/man3nsl/getpublickey.3nsl @@ -0,0 +1,93 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpublickey 3NSL "10 Nov 2005" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +getpublickey, getsecretkey, publickey \- retrieve public or secret key +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpc.h> +#include <rpc/key_prot.h> + +\fBint\fR \fBgetpublickey\fR(\fBconst char\fR \fInetname[MAXNETNAMELEN]\fR, + \fBchar\fR \fIpublickey[HEXKEYBYTES+1]\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetsecretkey\fR(\fBconst char\fR \fInetname[MAXNETNAMELEN]\fR, + \fBchar\fR \fIsecretkey[HEXKEYBYTES+1]\fR,\fBconst char *\fR\fIpasswd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpublickey()\fR and \fBgetsecretkey()\fR functions get public and +secret keys for \fInetname\fR. The key may come from one of the following +sources: +.RS +4 +.TP +.ie t \(bu +.el o +\fB/etc/publickey\fR file. See \fBpublickey\fR(4). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBNIS\fR map ``publickey.byname'' or the \fBNIS+\fR table ``cred.org_dir''. +The sources and their lookup order are specified in the +\fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4). +.RE +.sp +.LP +\fBgetsecretkey()\fR has an extra argument, \fBpasswd\fR, which is used to +decrypt the encrypted secret key stored in the database. +.SH RETURN VALUES +.sp +.LP +Both routines return \fB1\fR if they are successful in finding the key. +Otherwise, the routines return \fB0\fR. The keys are returned as +null-terminated, hexadecimal strings. If the password supplied to +\fBgetsecretkey()\fR fails to decrypt the secret key, the routine will return 1 +but the \fIsecretkey\fR [0] will be set to \fINULL\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsecure_rpc\fR(3NSL), \fBnsswitch.conf\fR(4), \fBpublickey\fR(4), +\fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +If \fBgetpublickey()\fR gets the public key from any source other than NIS+, +all authenticated NIS+ operations may fail. To ensure that this does not +happen, edit the \fBnsswitch.conf\fR(4) file to make sure that the public key +is obtained from NIS+. +.SS "NOTES" +.sp +.LP +NIS+ might not be supported in future releases of the Solaris operating system. +Tools to aid the migration from NIS+ to LDAP are available in the current +Solaris release. For more information, visit +http://www.sun.com/directory/nisplus/transition.html. diff --git a/usr/src/man/man3nsl/getrpcbyname.3nsl b/usr/src/man/man3nsl/getrpcbyname.3nsl new file mode 100644 index 0000000000..bb1924b7a0 --- /dev/null +++ b/usr/src/man/man3nsl/getrpcbyname.3nsl @@ -0,0 +1,230 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getrpcbyname 3NSL "20 Feb 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +getrpcbyname, getrpcbyname_r, getrpcbynumber, getrpcbynumber_r, getrpcent, +getrpcent_r, setrpcent, endrpcent \- get RPC entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lnsl\fR [ \fIlibrary\fR ... ] +#include <rpc/rpcent.h> + + + +\fBstruct rpcent *\fR\fBgetrpcbyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct rpcent *\fR\fBgetrpcbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct rpcent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct rpcent *\fR\fBgetrpcbynumber\fR(\fBconst int\fR \fInumber\fR); +.fi + +.LP +.nf +\fBstruct rpcent *\fR\fBgetrpcbynumber_r\fR(\fBconst int\fR \fInumber\fR, \fBstruct rpcent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct rpcent *\fR\fBgetrpcent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct rpcent *\fR\fBgetrpcent_r\fR(\fBstruct rpcent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetrpcent\fR(\fBconst int\fR \fIstayopen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendrpcent\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain entries for RPC (Remote Procedure Call) +services. An entry may come from any of the sources for \fBrpc\fR specified in +the \fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)). +.sp +.LP +\fBgetrpcbyname()\fR searches for an entry with the RPC service name specified +by the parameter \fIname\fR. +.sp +.LP +\fBgetrpcbynumber()\fR searches for an entry with the RPC program number +\fInumber\fR. +.sp +.LP +The functions \fBsetrpcent()\fR, \fBgetrpcent()\fR, and \fBendrpcent()\fR are +used to enumerate RPC entries from the database. +.sp +.LP +\fBsetrpcent()\fR sets (or resets) the enumeration to the beginning of the set +of RPC entries. This function should be called before the first call to +\fBgetrpcent()\fR. Calls to \fBgetrpcbyname()\fR and \fBgetrpcbynumber()\fR +leave the enumeration position in an indeterminate state. If the +\fIstayopen\fR flag is non-zero, the system may keep allocated resources such +as open file descriptors until a subsequent call to \fBendrpcent()\fR. +.sp +.LP +Successive calls to \fBgetrpcent()\fR return either successive entries or +\fBNULL,\fR indicating the end of the enumeration. +.sp +.LP +\fBendrpcent()\fR may be called to indicate that the caller expects to do no +further RPC entry retrieval operations; the system may then deallocate +resources it was using. It is still allowed, but possibly less efficient, for +the process to call more RPC entry retrieval functions after calling +\fBendrpcent()\fR. +.SS "Reentrant Interfaces" +.sp +.LP +The functions \fBgetrpcbyname()\fR, \fBgetrpcbynumber()\fR, and +\fBgetrpcent()\fR use static storage that is re-used in each call, making these +routines unsafe for use in multithreaded applications. +.sp +.LP +The functions \fBgetrpcbyname_r()\fR, \fBgetrpcbynumber_r()\fR, and +\fBgetrpcent_r()\fR provide reentrant interfaces for these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the ``\fB_r\fR'' suffix. The reentrant +interfaces, however, use buffers supplied by the caller to store returned +results, and are safe for use in both single-threaded and multithreaded +applications. +.sp +.LP +Each reentrant interface takes the same parameters as its non-reentrant +counterpart, as well as the following additional parameters. The parameter +\fIresult\fR must be a pointer to a \fBstruct rpcent\fR structure allocated by +the caller. On successful completion, the function returns the RPC entry in +this structure. The parameter \fIbuffer\fR must be a pointer to a buffer +supplied by the caller. This buffer is used as storage space for the RPC entry +data. All of the pointers within the returned \fBstruct rpcent\fR \fIresult\fR +point to data stored within this buffer (see \fBRETURN VALUES\fR). The buffer +must be large enough to hold all of the data associated with the RPC entry. The +parameter \fIbuflen\fR should give the size in bytes of the buffer indicated by +\fIbuffer\fR. +.sp +.LP +For enumeration in multithreaded applications, the position within the +enumeration is a process-wide property shared by all threads. \fBsetrpcent()\fR +may be used in a multithreaded application but resets the enumeration position +for all threads. If multiple threads interleave calls to \fBgetrpcent_r()\fR, +the threads will enumerate disjoint subsets of the RPC entry database. +.sp +.LP +Like their non-reentrant counterparts, \fBgetrpcbyname_r()\fR and +\fBgetrpcbynumber_r()\fR leave the enumeration position in an indeterminate +state. +.SH RETURN VALUES +.sp +.LP +RPC entries are represented by the \fBstruct rpcent\fR structure defined in +\fB<rpc/rpcent.h>\fR: +.sp +.in +2 +.nf +struct rpcent { + char *r_name; /* name of this rpc service + char **r_aliases; /* zero-terminated list of alternate names */ + int r_number; /* rpc program number */ +}; +.fi +.in -2 + +.sp +.LP +The functions \fBgetrpcbyname()\fR, \fBgetrpcbyname_r(\|)\fR, +\fBgetrpcbynumber(\|)\fR, and \fBgetrpcbynumber_r()\fR each return a pointer to +a \fBstruct rpcent\fR if they successfully locate the requested entry; +otherwise they return \fBNULL.\fR +.sp +.LP +The functions \fBgetrpcent()\fR and \fBgetrpcent_r()\fR each return a pointer +to a \fBstruct rpcent\fR if they successfully enumerate an entry; otherwise +they return \fBNULL,\fR indicating the end of the enumeration. +.sp +.LP +The functions \fBgetrpcbyname()\fR, \fBgetrpcbynumber()\fR, and +\fBgetrpcent()\fR use static storage, so returned data must be copied before a +subsequent call to any of these functions if the data is to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgetrpcbyname_r()\fR, +\fBgetrpcbynumber_r()\fR, and \fBgetrpcent_r()\fR is non-NULL, it is always +equal to the \fIresult\fR pointer that was supplied by the caller. +.SH ERRORS +.sp +.LP +The reentrant functions \fBgetrpcyname_r()\fR, \fBgetrpcbynumber_r(\|)\fR and +\fBgetrpcent_r()\fR will return \fBNULL\fR and set \fBerrno\fR to \fBERANGE\fR +if the length of the buffer supplied by caller is not large enough to store the +result. See \fBIntro\fR(2) for the proper usage and interpretation of +\fBerrno\fR in multithreaded applications. +.SH FILES +.sp +.LP +\fB/etc/rpc\fR +.sp +.LP +\fB/etc/nsswitch.conf\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelT{ +See "Reentrant Interfaces" in \fBDESCRIPTION\fR. +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpcinfo\fR(1M), \fBrpc\fR(3NSL), \fBnsswitch.conf\fR(4), \fBrpc\fR(4), +\fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +The reentrant interfaces \fBgetrpcbyname_r()\fR, \fBgetrpcbynumber_r()\fR, and +\fBgetrpcent_r()\fR are included in this release on an uncommitted basis only, +and are subject to change or removal in future minor releases. +.SH NOTES +.sp +.LP +When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On +Multithreaded Applications\fR, for information about the use of the +\fB_REENTRANT\fR flag. +.sp +.LP +Use of the enumeration interfaces \fBgetrpcent()\fR and \fBgetrpcent_r()\fR is +discouraged; enumeration may not be supported for all database sources. The +semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4). diff --git a/usr/src/man/man3nsl/netdir.3nsl b/usr/src/man/man3nsl/netdir.3nsl new file mode 100644 index 0000000000..9219998267 --- /dev/null +++ b/usr/src/man/man3nsl/netdir.3nsl @@ -0,0 +1,350 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH netdir 3NSL "28 Jan 2005" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +netdir, netdir_getbyname, netdir_getbyaddr, netdir_free, netdir_options, +taddr2uaddr, uaddr2taddr, netdir_perror, netdir_sperror, netdir_mergeaddr \- +generic transport name-to-address translation +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...] +#include <netdir.h> + +\fBint\fR \fBnetdir_getbyname\fR(\fBstruct netconfig *\fR\fIconfig\fR, + \fBstruct nd_hostserv *\fR\fIservice\fR, \fBstruct nd_addrlist **\fR\fIaddrs\fR); +.fi + +.LP +.nf +\fBint\fR \fBnetdir_getbyaddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, + \fBstruct nd_hostservlist **\fR\fIservice\fR, \fBstruct netbuf *\fR\fInetaddr\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBnetdir_free\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIstruct_type\fR); +.fi + +.LP +.nf +\fBint\fR \fBnetdir_options\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBint\fR \fIoption\fR, \fBint\fR \fIfildes\fR, + \fBchar *\fR\fIpoint_to_args\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBtaddr2uaddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBstruct netbuf *\fR\fIaddr\fR); +.fi + +.LP +.nf +\fBstruct netbuf *\fR\fBuaddr2taddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBchar *\fR\fIuaddr\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBnetdir_perror\fR(\fBchar *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBnetdir_sperror\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBnetdir\fR functions provide a generic interface for name-to-address +mapping that will work with all transport protocols. This interface provides a +generic way for programs to convert transport specific addresses into common +structures and back again. The \fBnetconfig\fR structure, described on the +\fBnetconfig\fR(4) manual page, identifies the transport. +.sp +.LP +The \fBnetdir_getbyname()\fR function maps the machine name and service name in +the \fBnd_hostserv\fR structure to a collection of addresses of the type +understood by the transport identified in the \fBnetconfig\fR structure. This +function returns all addresses that are valid for that transport in the +\fBnd_addrlist\fR structure. The \fBnd_hostserv\fR structure contains the +following members: +.sp +.in +2 +.nf +char *h_host; /* host name */ +char *h_serv; /* service name */ +.fi +.in -2 + +.sp +.LP +The \fBnd_addrlist\fR structure contains the following members: +.sp +.in +2 +.nf +int n_cnt; /* number of addresses */ +struct netbuf *n_addrs; +.fi +.in -2 + +.sp +.LP +The \fBnetdir_getbyname()\fR function accepts some special-case host names. The +host names are defined in <\fBnetdir.h\fR>. The currently defined host names +are: +.sp +.ne 2 +.mk +.na +\fB\fBHOST_SELF\fR\fR +.ad +.RS 21n +.rt +Represents the address to which local programs will bind their endpoints. +\fBHOST_SELF\fR differs from the host name provided by \fBgethostname\fR(3C), +which represents the address to which \fIremote\fR programs will bind their +endpoints. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHOST_ANY\fR\fR +.ad +.RS 21n +.rt +Represents any host accessible by this transport provider. \fBHOST_ANY\fR +allows applications to specify a required service without specifying a +particular host name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHOST_SELF_CONNECT\fR\fR +.ad +.RS 21n +.rt +Represents the host address that can be used to connect to the local host. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHOST_BROADCAST\fR\fR +.ad +.RS 21n +.rt +Represents the address for all hosts accessible by this transport provider. +Network requests to this address are received by all machines. +.RE + +.sp +.LP +All fields of the \fBnd_hostserv\fR structure must be initialized. +.sp +.LP +To find the address of a given host and service on all available transports, +call the \fBnetdir_getbyname()\fR function with each \fBstruct netconfig\fR +structure returned by \fBgetnetconfig\fR(3NSL). +.sp +.LP +The \fBnetdir_getbyaddr()\fR function maps addresses to service names. The +function returns \fIservice\fR, a list of host and service pairs that yield +these addresses. If more than one tuple of host and service name is returned, +the first tuple contains the preferred host and service names: +.sp +.in +2 +.nf +struct nd_hostservlist { + int *h_cnt; /* number of hostservs found */ + struct hostserv *h_hostservs; +} +.fi +.in -2 + +.sp +.LP +The \fBnetdir_free()\fR structure is used to free the structures allocated by +the name to address translation functions. The \fIptr\fR parameter points to +the structure that has to be freed. The parameter \fBstruct_type\fR identifies +the structure: +.sp +.in +2 +.nf +struct netbuf ND_ADDR +struct nd_addrlist ND_ADDRLIST +struct hostserv ND_HOSTSERV +struct nd_hostservlist ND_HOSTSERVLIST +.fi +.in -2 + +.sp +.LP +The \fBfree()\fR function is used to free the universal address returned by the +\fBtaddr2uaddr()\fR function. +.sp +.LP +The \fBnetdir_options()\fR function is used to do all transport-specific setups +and option management. \fIfildes\fR is the associated file descriptor. +\fIoption\fR, \fIfildes\fR, and \fIpointer_to_args\fR are passed to the +\fBnetdir_options()\fR function for the transport specified in \fIconfig\fR. +Currently four values are defined for \fIoption\fR: +.br +.in +2 +\fBND_SET_BROADCAST\fR +.in -2 +.br +.in +2 +\fBND_SET_RESERVEDPORT\fR +.in -2 +.br +.in +2 +\fBND_CHECK_RESERVEDPORT\fR +.in -2 +.br +.in +2 +\fBND_MERGEADDR\fR +.in -2 +.sp +.LP +The \fBtaddr2uaddr()\fR and \fBuaddr2taddr()\fR functions support translation +between universal addresses and \fBTLI\fR type \fBnetbufs\fR. The +\fBtaddr2uaddr()\fR function takes a \fBstruct\fR \fBnetbuf\fR data structure +and returns a pointer to a string that contains the universal address. It +returns \fINULL\fR if the conversion is not possible. This is not a fatal +condition as some transports do not support a universal address form. +.sp +.LP +The \fBuaddr2taddr()\fR function is the reverse of the \fBtaddr2uaddr()\fR +function. It returns the \fBstruct netbuf\fR data structure for the given +universal address. +.sp +.LP +If a transport provider does not support an option, \fBnetdir_options\fR +returns \fB-1\fR and the error message can be printed through +\fBnetdir_perror()\fR or \fBnetdir_sperror()\fR. +.sp +.LP +The specific actions of each option follow. +.sp +.ne 2 +.mk +.na +\fB\fBND_SET_BROADCAST\fR\fR +.ad +.RS 25n +.rt +Sets the transport provider up to allow broadcast if the transport supports +broadcast. \fIfildes\fR is a file descriptor into the transport, that is, the +result of a \fBt_open\fR of \fB/dev/udp\fR. \fIpointer_to_args\fR is not used. +If this completes, broadcast operations can be performed on file descriptor +\fIfildes\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBND_SET_RESERVEDPORT\fR\fR +.ad +.RS 25n +.rt +Allows the application to bind to a reserved port if that concept exists for +the transport provider. \fIfildes\fR is an unbound file descriptor into the +transport. If \fIpointer_to_args\fR is \fINULL,\fR \fIfildes\fR is bound to a +reserved port. If \fIpointer_to_args\fR is a pointer to a \fBnetbuf\fR +structure, an attempt is made to bind to any reserved port on the specified +address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBND_CHECK_RESERVEDPORT\fR\fR +.ad +.RS 25n +.rt +Used to verify that the address corresponds to a reserved port if that concept +exists for the transport provider. \fIfildes\fR is not used. +\fIpointer_to_args\fR is a pointer to a \fBnetbuf\fR structure that contains +the address. This option returns \fB0\fR only if the address specified in +\fIpointer_to_args\fR is reserved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBND_MERGEADDR\fR\fR +.ad +.RS 25n +.rt +Used to take a ``local address'' such as a \fB0.0.0.0\fR TCP address and return +a ``real address'' to which client machines can connect. \fIfildes\fR is not +used. \fIpointer_to_args\fR is a pointer to a \fBstruct nd_mergearg\fR which +has the following members: +.sp +.in +2 +.nf +\fBchar\fR \fIs_uaddr;\fR /* server's universal address */ +\fBchar\fR \fIc_uaddr;\fR /* client's universal address */ +\fBchar\fR \fIm_uaddr;\fR /* the result */ +.fi +.in -2 + +If \fBs_uaddr\fR is an address such as \fB0.0.0.0.1.12\fR, and the call is +successful \fBm_uaddr\fR is set to an address such as \fB192.11.109.89.1.12\fR. +For most transports, \fBm_uaddr\fR is identical to \fBs_uaddr\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBnetdir_perror()\fR function prints an error message in standard output +that states the cause of a name-to-address mapping failure. The error message +is preceded by the string given as an argument. +.sp +.LP +The \fBnetdir_sperror()\fR function returns a string with an error message that +states the cause of a name-to-address mapping failure. +.sp +.LP +The \fBnetdir_sperror()\fR function returns a pointer to a buffer which +contains the error message string. The buffer is overwritten on each call. In +multithreaded applications, thise buffer is implemented as thread-specific +data. +.sp +.LP +The \fBnetdir_getbyaddr()\fR function returns \fB0\fR on success and a non-zero +value on failure. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgethostname\fR(3C), \fBgetnetconfig\fR(3NSL), \fBgetnetpath\fR(3NSL), +\fBnetconfig\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/nlsgetcall.3nsl b/usr/src/man/man3nsl/nlsgetcall.3nsl new file mode 100644 index 0000000000..e95c697c2e --- /dev/null +++ b/usr/src/man/man3nsl/nlsgetcall.3nsl @@ -0,0 +1,96 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nlsgetcall 3NSL "14 Nov 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +nlsgetcall \- get client's data passed via the listener +.SH SYNOPSIS +.LP +.nf +#include <sys/tiuser.h> + + + +\fBstruct t_call *\fR\fBnlsgetcall\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBnlsgetcall()\fR allows server processes started by the listener process to +access the client's \fBt_call\fR structure, that is, the \fIsndcall\fR argument +of \fBt_connect\fR(3NSL). +.sp +.LP +The \fBt_call\fR structure returned by \fBnlsgetcall()\fR can be released using +\fBt_free\fR(3NSL). +.sp +.LP +\fBnlsgetcall()\fR returns the address of an allocated \fBt_call\fR structure +or NULL if a \fBt_call\fR structure cannot be allocated. If the \fBt_alloc()\fR +succeeds, undefined environment variables are indicated by a negative \fIlen\fR +field in the appropriate \fBnetbuf\fR structure. A \fIlen\fR field of zero in +the \fBnetbuf\fR structure is valid and means that the original buffer in the +listener's \fBt_call\fR structure was NULL. +.SH RETURN VALUES +.sp +.LP +A NULL pointer is returned if a \fBt_call\fR structure cannot be allocated by +\fBt_alloc()\fR. \fBt_errno\fR can be inspected for further error information. +Undefined environment variables are indicated by a negative length field +(\fIlen\fR) in the appropriate \fBnetbuf\fR structure. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/libnls.so.1\fR\fR +.ad +.RS 24n +.rt +shared object +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBnlsadmin\fR(1M), \fBgetenv\fR(3C), \fBt_alloc\fR(3NSL), +\fBt_connect\fR(3NSL), \fBt_error\fR(3NSL), \fBt_free\fR(3NSL), +\fBt_sync\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +The \fIlen\fR field in the \fBnetbuf\fR structure is defined as being unsigned. +In order to check for error returns, it should first be cast to an int. +.sp +.LP +The listener process limits the amount of user data (\fIudata\fR) and options +data (\fIopt\fR) to 128 bytes each. Address data \fIaddr\fR is limited to 64 +bytes. If the original data was longer, no indication of overflow is given. +.SH NOTES +.sp +.LP +Server processes must call \fBt_sync\fR(3NSL) before calling this routine. +.sp +.LP +This interface is unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/nlsprovider.3nsl b/usr/src/man/man3nsl/nlsprovider.3nsl new file mode 100644 index 0000000000..ca09b92dd4 --- /dev/null +++ b/usr/src/man/man3nsl/nlsprovider.3nsl @@ -0,0 +1,67 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nlsprovider 3NSL "14 Nov 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +nlsprovider \- get name of transport provider +.SH SYNOPSIS +.LP +.nf +\fBchar *\fR\fBnlsprovider\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBnlsprovider()\fR returns a pointer to a null-terminated character string +which contains the name of the transport provider as placed in the environment +by the listener process. If the variable is not defined in the environment, a +NULL pointer is returned. +.sp +.LP +The environment variable is only available to server processes started by the +listener process. +.SH RETURN VALUES +.sp +.LP +If the variable is not defined in the environment, a NULL pointer is returned. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/libnls.so.1\fR\fR +.ad +.RS 24n +.rt +shared object +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBnlsadmin\fR(1M), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +This interface is unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/nlsrequest.3nsl b/usr/src/man/man3nsl/nlsrequest.3nsl new file mode 100644 index 0000000000..d1887634f2 --- /dev/null +++ b/usr/src/man/man3nsl/nlsrequest.3nsl @@ -0,0 +1,139 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nlsrequest 3NSL "14 Nov 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +nlsrequest \- format and send listener service request message +.SH SYNOPSIS +.LP +.nf +#include <listen.h> +\fBint\fR \fBnlsrequest\fR(\fBint\fR \fIfildes\fR, \fBchar \fR*\fIservice_code\fR); +\fBextern int\fR \fI_nlslogt_errno\fR; +\fBextern char\fR *\fI_nlsrmsg\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +Given a virtual circuit to a listener process (\fIfildes\fR) and a service +code of a server process, \fBnlsrequest()\fR formats and sends a \fIservice +request message\fR to the remote listener process requesting that it start the +given service. \fBnlsrequest()\fR waits for the remote listener process to +return a \fIservice request response message\fR, which is made available to +the caller in the static, null-terminated data buffer pointed to by +\fB_nlsrmsg\fR. The \fIservice request response message\fR includes a success +or failure code and a text message. The entire message is printable. +.SH RETURN VALUES +.sp +.LP +The success or failure code is the integer return code from \fBnlsrequest()\fR. +Zero indicates success, other negative values indicate \fBnlsrequest()\fR +failures as follows: +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +Error encountered by \fBnlsrequest()\fR, see \fBt_errno\fR. +.RE + +.sp +.LP +Positive values are error return codes from the \fIlistener\fR process. +Mnemonics for these codes are defined in \fB<listen.h>\fR\&. +.sp +.ne 2 +.mk +.na +\fB\fB2\fR\fR +.ad +.RS 5n +.rt +Request message not interpretable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB3\fR\fR +.ad +.RS 5n +.rt +Request service code unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB4\fR\fR +.ad +.RS 5n +.rt +Service code known, but currently disabled. +.RE + +.sp +.LP +If non-null, \fB_nlsrmsg\fR contains a pointer to a static, null-terminated +character buffer containing the \fIservice request response message\fR. Note +that both \fB_nlsrmsg\fR and the data buffer are overwritten by each call to +\fBnlsrequest()\fR. +.sp +.LP +If \fB_nlslog\fR is non-zero, \fBnlsrequest()\fR prints error messages on +stderr. Initially, \fB_nlslog\fR is zero. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/libnls.so.1\fR\fR +.ad +.RS 24n +.rt +shared object +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBnlsadmin\fR(1M), \fBt_error\fR(3NSL), \fBt_snd\fR(3NSL), \fBt_rcv\fR(3NSL), +\fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +\fBnlsrequest()\fR cannot always be certain that the remote server process has +been successfully started. In this case, \fBnlsrequest()\fR returns with no +indication of an error and the caller will receive notification of a disconnect +event by way of a \fBT_LOOK\fR error before or during the first \fBt_snd()\fR +or \fBt_rcv()\fR call. +.SH NOTES +.sp +.LP +These interfaces are unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/rpc.3nsl b/usr/src/man/man3nsl/rpc.3nsl new file mode 100644 index 0000000000..4213124da8 --- /dev/null +++ b/usr/src/man/man3nsl/rpc.3nsl @@ -0,0 +1,1502 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc 3NSL "5 Jun 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc \- library routines for remote procedure calls +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lnsl\fR [ \fIlibrary\fR ... ] +#include <rpc/rpc.h> +#include <netconfig.h> +.fi + +.SH DESCRIPTION +.sp +.LP +These routines allow C language programs to make procedure calls on other +machines across a network. First, the client sends a request to the server. On +receipt of the request, the server calls a dispatch routine to perform the +requested service, and then sends back a reply. +.sp +.LP +All \fBRPC\fR routines require the header \fB<rpc/rpc.h>\fR\&. Routines that +take a \fBnetconfig\fR structure also require that \fB<netconfig.h>\fR be +included. Applications using \fBRPC\fR and \fBXDR\fR routines should be +linked with the \fBlibnsl\fR library. +.SS "Multithread Considerations" +.sp +.LP +In the case of multithreaded applications, the \fB-mt\fR option must be +specified on the command line at compilation time to enable a thread-specific +version of \fBrpc_createerr()\fR. See \fBrpc_clnt_create\fR(3NSL) and +\fBthreads\fR(5). +.sp +.LP +When used in multithreaded applications, client-side routines are MT-Safe. +\fBCLIENT\fR handles can be shared between threads; however, in this +implementation, requests by different threads are serialized (that is, the +first request will receive its results before the second request is sent). See +\fBrpc_clnt_create\fR(3NSL). +.sp +.LP +When used in multithreaded applications, server-side routines are usually +Unsafe. In this implementation the service transport handle, \fBSVCXPRT\fR +contains a single data area for decoding arguments and encoding results. See +\fBrpc_svc_create\fR(3NSL). Therefore, this structure cannot be freely shared +between threads that call functions that do this. Routines that are affected +by this restriction are marked as unsafe for MT applications. See +\fBrpc_svc_calls\fR(3NSL). +.SS "Nettyp" +.sp +.LP +Some of the high-level \fBRPC\fR interface routines take a \fInettype\fR string +as one of the parameters (for example, \fBclnt_create()\fR, \fBsvc_create()\fR, +\fBrpc_reg()\fR, \fBrpc_call()\fR). This string defines a class of transports +which can be used for a particular application. +.sp +.LP +\fInettype\fR can be one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBnetpath\fR\fR +.ad +.RS 14n +.rt +Choose from the transports which have been indicated by their token names in +the \fBNETPATH\fR environment variable. If \fBNETPATH\fR is unset or +\fINULL\fR, it defaults to \fBvisible\fR. \fBnetpath\fR is the default +\fInettype\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvisible\fR\fR +.ad +.RS 14n +.rt +Choose the transports which have the visible flag (\fBv\fR) set in the +\fB/etc/netconfig\fR file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcircuit_v\fR\fR +.ad +.RS 14n +.rt +This is same as \fBvisible\fR except that it chooses only the connection +oriented transports (semantics \fBtpi_cots\fR or \fBtpi_cots_ord\fR) from the +entries in the \fB/etc/netconfig\fR file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdatagram_v\fR\fR +.ad +.RS 14n +.rt +This is same as \fBvisible\fR except that it chooses only the connectionless +datagram transports (semantics \fBtpi_clts\fR) from the entries in the +\fB/etc/netconfig\fR file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcircuit_n\fR\fR +.ad +.RS 14n +.rt +This is same as \fBnetpath\fR except that it chooses only the connection +oriented datagram transports (semantics \fBtpi_cots\fR or \fBtpi_cots_ord\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdatagram_n\fR\fR +.ad +.RS 14n +.rt +This is same as \fBnetpath\fR except that it chooses only the connectionless +datagram transports (semantics \fBtpi_clts\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBudp\fR\fR +.ad +.RS 14n +.rt +This refers to Internet \fBUDP.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtcp\fR\fR +.ad +.RS 14n +.rt +This refers to Internet \fBTCP.\fR +.RE + +.sp +.LP +If \fInettype\fR is \fINULL\fR, it defaults to \fBnetpath\fR. The transports +are tried in left to right order in the \fBNETPATH\fR variable or in top to +down order in the \fB/etc/netconfig\fR file. +.SS "Derived Types" +.sp +.LP +In a 64-bit environment, the derived types are defined as follows: +.sp + +.sp +.TS +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +\fBtypedef\fR\fBuint32_t\fR\fBrpcprog_t;\fR +\fBtypedef\fR\fBuint32_t\fR\fBrpcvers_t;\fR +\fBtypedef\fR\fBuint32_t\fR\fBrpcproc_t;\fR +\fBtypedef\fR\fBuint32_t\fR\fBrpcprot_t;\fR +\fBtypedef\fR\fBuint32_t\fR\fBrpcport_t;\fR +\fBtypedef\fR\fBint32_t\fR\fBrpc_inline_t;\fR +.TE + +.sp +.LP +In a 32-bit environment, the derived types are defined as follows: +.sp + +.sp +.TS +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +\fBtypedef\fR\fBunsigned long\fR\fBrpcprog_t;\fR +\fBtypedef\fR\fBunsigned long\fR\fBrpcvers_t;\fR +\fBtypedef\fR\fBunsigned long\fR\fBrpcproc_t;\fR +\fBtypedef\fR\fBunsigned long\fR\fBrpcprot_t;\fR +\fBtypedef\fR\fBunsigned long\fR\fBrpcport_t;\fR +\fBtypedef\fR\fBlong\fR\fBrpc_inline_t;\fR +.TE + +.SS "Data Structures" +.sp +.LP +Some of the data structures used by the \fBRPC\fR package are shown below. +.SS "The \fBAUTH\fR Structure" +.sp +.in +2 +.nf +union des_block { + struct { + u_int32 high; + u_int32 low; + } key; +char c[8]; +}; +typedef union des_block des_block; +extern bool_t xdr_des_block(\|); +/* + * Authentication info. Opaque to client. +*/ +struct opaque_auth { + enum_t oa_flavor; /* flavor of auth */ + caddr_t oa_base; /* address of more auth stuff */ + uint_t oa_length; /* not to exceed MAX_AUTH_BYTES */ +}; +/* + * Auth handle, interface to client side authenticators. +*/ + typedef struct { + struct opaque_auth ah_cred; + struct opaque_auth ah_verf; + union des_block ah_key; + struct auth_ops { + void(*ah_nextverf)(\|); + int(*ah_marshal)(\|); /* nextverf & serialize */ + int(*ah_validate)(\|); /* validate verifier */ + int(*ah_refresh)(\|); /* refresh credentials */ + void(*ah_destroy)(\|); /* destroy this structure */ + } *ah_ops; + caddr_t ah_private; +} AUTH; +.fi +.in -2 + +.SS "The \fBCLIENT\fR Structure" +.sp +.in +2 +.nf +/* + * Client rpc handle. + * Created by individual implementations. + * Client is responsible for initializing auth. + */ + typedef struct { + AUTH *cl_auth; /* authenticator */ + struct clnt_ops { + enum clnt_stat (*cl_call)(\|); /* call remote procedure */ + void (*cl_abort)(\|); /* abort a call */ + void (*cl_geterr)(\|); /* get specific error code */ + bool_t (*cl_freeres)(\|); /* frees results */ + void (*cl_destroy)(\|); /* destroy this structure */ + bool_t (*cl_control)(\|); /* the ioctl(\|) of rpc */ + int (*cl_settimers)(\|); /* set rpc level timers */ + } *cl_ops; + caddr_t cl_private; /* private stuff */ + char *cl_netid; /* network identifier */ + char *cl_tp; /* device name */ +} CLIENT; +.fi +.in -2 + +.SS "The \fBSVCXPRT\fR Structure" +.sp +.in +2 +.nf +enum xprt_stat { +XPRT_DIED, +XPRT_MOREREQS, +XPRT_IDLE +}; +/* + * Server side transport handle + */ +typedef struct { + int xp_fd; /* file descriptor for the + ushort_t xp_port; /* obsolete */ + struct xp_ops { + bool_t (*xp_recv)(\|); /* receive incoming requests */ + enum xprt_stat (*xp_stat)(\|); /* get transport status */ + bool_t (*xp_getargs)(\|); /* get arguments */ + bool_t (*xp_reply)(\|); /* send reply */ + bool_t (*xp_freeargs)(\|); /* free mem allocated + for args */ + void (*xp_destroy)(\|); /* destroy this struct */ + } *xp_ops; + int xp_addrlen; /* length of remote addr. + Obsolete */ + char *xp_tp; /* transport provider device + name */ + char *xp_netid; /* network identifier */ + struct netbuf xp_ltaddr; /* local transport address */ + struct netbuf xp_rtaddr; /* remote transport address */ + char xp_raddr[16]; /* remote address. Obsolete */ + struct opaque_auth xp_verf; /* raw response verifier */ + caddr_t xp_p1; /* private: for use + by svc ops */ + caddr_t xp_p2; /* private: for use + by svc ops */ + caddr_t xp_p3; /* private: for use + by svc lib */ + int xp_type /* transport type */ +} SVCXPRT; +.fi +.in -2 + +.SS "The \fBsvc_reg\fR Structure" +.sp +.in +2 +.nf +struct svc_req { + rpcprog_t rq_prog; /* service program number */ + rpcvers_t rq_vers; /* service protocol version */ + rpcproc_t rq_proc; /* the desired procedure */ + struct opaque_auth rq_cred; /* raw creds from the wire */ + caddr_t rq_clntcred; /* read only cooked cred */ + SVCXPRT *rq_xprt; /* associated transport */ + +}; +.fi +.in -2 + +.SS "The \fBXDR\fR Structure" +.sp +.in +2 +.nf +/* + * XDR operations. + * XDR_ENCODE causes the type to be encoded into the stream. + * XDR_DECODE causes the type to be extracted from the stream. + * XDR_FREE can be used to release the space allocated by an XDR_DECODE + * request. + */ +enum xdr_op { + XDR_ENCODE=0, + XDR_DECODE=1, + XDR_FREE=2 +}; +/* + * This is the number of bytes per unit of external data. + */ +#define BYTES_PER_XDR_UNIT (4) +#define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) / + BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT) +/* + * A xdrproc_t exists for each data type which is to be encoded or + * decoded. The second argument to the xdrproc_t is a pointer to + * an opaque pointer. The opaque pointer generally points to a + * structure of the data type to be decoded. If this points to 0, + * then the type routines should allocate dynamic storage of the + * appropriate size and return it. + * bool_t (*xdrproc_t)(XDR *, caddr_t *); + */ +typedef bool_t (*xdrproc_t)(\|); +/* + * The XDR handle. + * Contains operation which is being applied to the stream, + * an operations vector for the particular implementation + */ +typedef struct { + +enum xdr_op x_op; /* operation; fast additional param */ +struct xdr_ops { + +bool_t (*x_getlong)(\|); /* get long from underlying stream */ +bool_t (*x_putlong)(\|); /* put long to underlying stream */ +bool_t (*x_getbytes)(\|); /* get bytes from underlying stream */ +bool_t (*x_putbytes)(\|); /* put bytes to underlying stream */ +uint_t (*x_getpostn)(\|); /* returns bytes off from beginning */ +bool_t (*x_setpostn)(\|); /* reposition the stream */ +rpc_inline_t *(*x_inline)(\|); /* buf quick ptr to buffered data */ +void (*x_destroy)(\|); /* free privates of this xdr_stream */ +bool_t (*x_control)(\|); /* changed/retrieve client object info*/ +bool_t (*x_getint32)(\|); /* get int from underlying stream */ +bool_t (*x_putint32)(\|); /* put int to underlying stream */ + +} *x_ops; + +caddr_t x_public; /* users' data */ +caddr_t x_priv /* pointer to private data */ +caddr_t x_base; /* private used for position info */ +int x_handy; /* extra private word */ +XDR; +.fi +.in -2 + +.SS "Index to Routines" +.sp +.LP +The following table lists \fBRPC\fR routines and the manual reference pages on +which they are described: +.sp +.ne 2 +.mk +.na +\fB\fBRPC Routine\fR\fR +.ad +.RS 27n +.rt +\fBManual Reference Page\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauth_destroy\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_auth\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthdes_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthdes_getucred\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthdes_seccreate\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthnone_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_auth\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthsys_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_auth\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthsys_create_default\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_auth\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthunix_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthunix_create_default\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcallrpc\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_broadcast\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_call\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_control\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_destroy\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_dg_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_freeres\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_geterr\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_pcreateerror\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_perrno\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_perror\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_raw_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_spcreateerror\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_sperrno\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_sperror\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_tli_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_tp_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_udpcreate\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_vc_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclntraw_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnttcp_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclntudp_bufcreate\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBget_myaddress\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgetnetname\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhost2netname\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_decryptsession\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_encryptsession\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_gendes\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_setsecret\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnetname2host\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnetname2user\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_getmaps\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_getport\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_rmtcall\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_set\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_unset\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBregisterrpc\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_broadcast\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_broadcast_exp\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_call\fR\fR +.ad +.RS 27n +.rt +\fBrpc_clnt_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_reg\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_destroy\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_dg_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_dg_enablecache\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_fd_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_fds\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_freeargs\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_reg\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getargs\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_reg\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getcaller\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getreq\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getreqset\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getrpccaller\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_raw_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_reg\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_register\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_run\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_reg\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_sendreply\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_reg\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_tli_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_tp_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_unreg\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_unregister\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_vc_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_auth\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_decode\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_noproc\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_noprog\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_progvers\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_systemerr\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcerr_weakauth\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_err\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcfd_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcraw_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvctcp_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcudp_bufcreate\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcudp_create\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuser2netname\fR\fR +.ad +.RS 27n +.rt +\fBsecure_rpc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_accepted_reply\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_authsys_parms\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_authunix_parms\fR\fR +.ad +.RS 27n +.rt +\fBrpc_soc\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_callhdr\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_callmsg\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_opaque_auth\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_rejected_reply\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_replymsg\fR\fR +.ad +.RS 27n +.rt +\fBrpc_xdr\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxprt_register\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxprt_unregister\fR\fR +.ad +.RS 27n +.rt +\fBrpc_svc_calls\fR(3NSL) +.RE + +.SH FILES +.sp +.LP +\fB/etc/netconfig\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetnetconfig\fR(3NSL), \fBgetnetpath\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), +\fBrpc_clnt_calls\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), +\fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), +\fBrpc_svc_reg\fR(3NSL), \fBrpc_xdr\fR(3NSL), \fBrpcbind\fR(3NSL), +\fBsecure_rpc\fR(3NSL), \fBthreads\fR(5), \fBxdr\fR(3NSL), \fBnetconfig\fR(4), +\fBrpc\fR(4), \fBattributes\fR(5), \fBenviron\fR(5) diff --git a/usr/src/man/man3nsl/rpc_clnt_auth.3nsl b/usr/src/man/man3nsl/rpc_clnt_auth.3nsl new file mode 100644 index 0000000000..4cb34f8645 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_clnt_auth.3nsl @@ -0,0 +1,143 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_clnt_auth 3NSL "14 Jan 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_clnt_auth, auth_destroy, authnone_create, authsys_create, +authsys_create_default \- library routines for client side remote procedure +call authentication +.SH SYNOPSIS +.LP +.nf +\fBvoid\fR \fBauth_destroy\fR(\fBAUTH *\fR\fIauth\fR); +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthnone_create \fR(void) +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthsys_create\fR(\fBconst cha r*\fR\fIhost\fR, \fB const uid_t\fR \fIuid\fR, \fBconst gid_t\fR \fIgid\fR, + \fBconst int\fR \fIlen\fR, \fBconst gid_t *\fR\fIaup_gids\fR); +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthsys_create_default\fR(void) +.fi + +.SH DESCRIPTION +.sp +.LP +These routines are part of the \fBRPC\fR library that allows C language +programs to make procedure calls on other machines across the network, with +desired authentication. +.sp +.LP +These routines are normally called after creating the \fBCLIENT\fR handle. The +\fBcl_auth\fR field of the \fBCLIENT\fR structure should be initialized by the +\fBAUTH\fR structure returned by some of the following routines. The client's +authentication information is passed to the server when the \fBRPC\fR call is +made. +.sp +.LP +Only the \fINULL\fR and the \fBSYS\fR style of authentication is discussed +here. For the \fBDES\fR style authentication, please refer to +\fBsecure_rpc\fR(3NSL). +.sp +.LP +The \fINULL\fR and \fBSYS\fR style of authentication are safe in multithreaded +applications. For the MT-level of the \fBDES\fR style, see its pages. +.SS "Routines" +.sp +.LP +The following routines require that the header \fB<rpc/rpc.h>\fR be included +(see \fBrpc\fR(3NSL) for the definition of the \fBAUTH\fR data structure). +.sp +.in +2 +.nf +#include <rpc/rpc.h> +.fi +.in -2 +.sp + +.sp +.ne 2 +.mk +.na +\fB\fBauth_destroy()\fR\fR +.ad +.RS 26n +.rt +A function macro that destroys the authentication information associated with +\fIauth\fR. Destruction usually involves deallocation of private data +structures. The use of \fIauth\fR is undefined after calling +\fBauth_destroy()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthnone_create()\fR\fR +.ad +.RS 26n +.rt +Create and return an RPC authentication handle that passes nonusable +authentication information with each remote procedure call. This is the default +authentication used by RPC. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthsys_create()\fR\fR +.ad +.RS 26n +.rt +Create and return an \fBRPC\fR authentication handle that contains +\fBAUTH_SYS\fR authentication information. The parameter \fIhost\fR is the name +of the machine on which the information was created; \fIuid\fR is the user's +user \fBID;\fR \fIgid\fR is the user's current group \fBID;\fR \fIlen\fR and +\fIaup_gids\fR refer to a counted array of groups to which the user belongs. +.RE + +.sp +.ne 2 +.mk +.na +\fBauthsys_create_default\fR +.ad +.RS 26n +.rt +Call \fBauthsys_create()\fR with the appropriate parameters. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_clnt_calls\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), +\fBsecure_rpc\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_clnt_calls.3nsl b/usr/src/man/man3nsl/rpc_clnt_calls.3nsl new file mode 100644 index 0000000000..b931a88c90 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_clnt_calls.3nsl @@ -0,0 +1,361 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_clnt_calls 3NSL "1 Aug 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_clnt_calls, clnt_call, clnt_send, clnt_freeres, clnt_geterr, clnt_perrno, +clnt_perror, clnt_sperrno, clnt_sperror, rpc_broadcast, rpc_broadcast_exp, +rpc_call \- library routines for client side calls +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpc.h> + +\fBenum clnt_stat\fR \fBclnt_call\fR(\fBCLIENT *\fR\fIclnt\fR, \fBconst rpcproc_t\fR \fIprocnum\fR, + \fBconst xdrproc_t\fR \fIinproc\fR,\ \fBconst caddr_t\fR \fIin\fR, \fBconst xdrproc_t\fR \fIoutproc\fR, + \fBcaddr_t\fR \fIout\fR, \fBconst struct timeval\fR \fItout\fR); +.fi + +.LP +.nf +\fBenum clnt_stat\fR \fBclnt_send\fR (\fBCLIENT *\fR\fIclnt\fR, \fBconst u_long\fR + \fIprocnum\fR, \fBconst xdrproc_t\fR \fIproc\fR, \fBconst caddr_t\fR \fIin\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBclnt_freeres\fR(\fBCLIENT *\fR\fIclnt\fR, \fBconst xdrproc_t\fR \fIoutproc\fR, + \fBcaddr_t\fR \fIout\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBclnt_geterr\fR(\fBconst CLIENT *\fR\fIclnt\fR, \fBstruct rpc_err *\fR\fIerrp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBclnt_perrno\fR(\fBconst enum clnt_stat\fR \fIstat\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBclnt_perror\fR(\fBconst CLIENT *\fR\fIclnt\fR, \fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBclnt_sperrno\fR(\fBconst enum clnt_stat\fR \fIstat\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBclnt_sperror\fR(\fBconst CLIENT *\fR\fIclnt\fR, \fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBenum clnt_stat\fR \fBrpc_broadcast\fR(\fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst rpcproc_t\fR \fIprocnum\fR, + \fBconst xdrproc_t\fR\fIinproc\fR, \fBconst caddr_t\fR \fIin\fR, + \fBconst xdrproc_t\fR \fIoutproc\fR, \fBcaddr_t\fR \fIout\fR, + \fBconst resultproc_t\fR \fIeachresult\fR, \fBconst char *\fR\fInettype\fR); +.fi + +.LP +.nf +\fBenum clnt_stat\fR \fBrpc_broadcast_exp\fR(\fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR,\fBconst rpcproc_t\fR \fIprocnum\fR, + \fBconst xdrproc_t\fR\fIxargs\fR, \fBcaddr_t\fR \fIargsp\fR, \fBconst xdrproc_t\fR\fIxresults\fR, + \fBcaddr_t\fR \fIresultsp\fR, \fBconst resultproc_t\fR \fIeachresult\fR, \fBconst int\fR \fIinittime\fR, + \fBconst int\fR \fIwaittime\fR, \fBconst char *\fR\fInettype\fR); +.fi + +.LP +.nf +\fBenum clnt_stat\fR \fBrpc_call\fR(\fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst rpcproc_t\fR \fIprocnum\fR, \fBconst xdrproc_t\fR \fIinproc\fR, + \fBconst char *\fR\fIin\fR, \fBconst xdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR, \fBconst char *\fR\fInettype\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBRPC\fR library routines allow \fBC\fR language programs to make procedure +calls on other machines across the network. First, the client calls a procedure +to send a request to the server. Upon receipt of the request, the server calls +a dispatch routine to perform the requested service and then sends back a +reply. +.sp +.LP +The \fBclnt_call()\fR, \fBrpc_call()\fR, and \fBrpc_broadcast()\fR routines +handle the client side of the procedure call. The remaining routines deal with +error handling. +.sp +.LP +Some of the routines take a \fBCLIENT\fR handle as one of the parameters. A +\fBCLIENT\fR handle can be created by an \fBRPC\fR creation routine such as +\fBclnt_create()\fR. See \fBrpc_clnt_create\fR(3NSL). +.sp +.LP +These routines are safe for use in multithreaded applications. \fBCLIENT\fR +handles can be shared between threads; however, in this implementation requests +by different threads are serialized. In other words, the first request will +receive its results before the second request is sent. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBCLIENT\fR data structure. +.sp +.ne 2 +.mk +.na +\fB\fBclnt_call()\fR\fR +.ad +.RS 23n +.rt +A function macro that calls the remote procedure \fIprocnum\fR associated with +the client handle, \fIclnt\fR, which is obtained with an \fBRPC\fR client +creation routine such as \fBclnt_create()\fR. See \fBrpc_clnt_create\fR(3NSL). +The parameter \fIinproc\fR is the \fBXDR\fR function used to encode the +procedure's parameters, and \fIoutproc\fR is the \fBXDR\fR function used to +decode the procedure's results. \fIin\fR is the address of the procedure's +argument(s), and \fIout\fR is the address of where to place the result(s). +\fItout\fR is the time allowed for results to be returned, which is overridden +by a time-out set explicitly through \fBclnt_control()\fR. See +\fBrpc_clnt_create\fR(3NSL). +.sp +If the remote call succeeds, the status returned is \fBRPC_SUCCESS\fR. +Otherwise, an appropriate status is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_send()\fR\fR +.ad +.RS 23n +.rt +Use the \fBclnt_send()\fR function to call a remote asynchronous function. +.sp +The \fBclnt_send()\fR function calls the remote function \fBprocnum()\fR +associated with the client handle, \fIclnt\fR, which is obtained with an RPC +client creation routine such as \fBclnt_create()\fR. See +\fBrpc_clnt_create\fR(3NSL). The parameter \fIproc\fR is the XDR function used +to encode the procedure's parameters. The parameter \fIin\fR is the address of +the procedure's argument(s). +.sp +By default, the blocking I/O mode is used. See the \fBclnt_control\fR(3NSL) man +page for more information on I/O modes. +.sp +The \fBclnt_send()\fR function does not check if the program version number +supplied to \fBclnt_create()\fR is registered with the \fBrpcbind\fR service. +Use \fBclnt_create_vers()\fR instead of \fBclnt_create()\fR to check on +incorrect version number registration. \fBclnt_create_vers()\fR will return a +valid handle to the client only if a version within the range supplied to +\fBclnt_create_vers()\fR is supported by the server. +.sp +\fBRPC_SUCCESS\fR is returned when a request is successfully delivered to the +transport layer. This does not mean that the request was received. If an error +is returned, use the \fBclnt_getterr()\fR routine to find the failure status or +the \fBclnt_perrno()\fR routine to translate the failure status into error +messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_freeres()\fR\fR +.ad +.RS 23n +.rt +A function macro that frees any data allocated by the \fBRPC/XDR\fR system when +it decoded the results of an \fBRPC\fR call. The parameter \fIout\fR is the +address of the results, and \fIoutproc\fR is the \fBXDR\fR routine describing +the results. This routine returns \fB1\fR if the results were successfully +freed; otherwise it returns \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_geterr()\fR\fR +.ad +.RS 23n +.rt +A function macro that copies the error structure out of the client handle to +the structure at address \fIerrp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_perrno()\fR\fR +.ad +.RS 23n +.rt +Prints a message to standard error corresponding to the condition indicated by +\fIstat\fR. A newline is appended. It is normally used after a procedure call +fails for a routine for which a client handle is not needed, for instance +\fBrpc_call()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_perror()\fR\fR +.ad +.RS 23n +.rt +Prints a message to the standard error indicating why an \fBRPC\fR call failed; +\fIclnt\fR is the handle used to do the call. The message is prepended with +string \fIs\fR and a colon. A newline is appended. This routine is normally +used after a remote procedure call fails for a routine that requires a client +handle, for instance \fBclnt_call()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_sperrno()\fR\fR +.ad +.RS 23n +.rt +Takes the same arguments as \fBclnt_perrno()\fR, but instead of sending a +message to the standard error indicating why an \fBRPC\fR call failed, returns +a pointer to a string that contains the message. +.sp +\fBclnt_sperrno()\fR is normally used instead of \fBclnt_perrno()\fR when the +program does not have a standard error, as a program running as a server quite +likely does not. \fBclnt_sperrno()\fR is also used if the programmer does not +want the message to be output with \fBprintf()\fR, or if a message format +different than that supported by \fBclnt_perrno()\fR is to be used. See +\fBprintf\fR(3C). Unlike \fBclnt_sperror()\fR and \fBclnt_spcreaterror()\fR, +\fBclnt_sperrno()\fR does not return a pointer to static data. Therefore, the +result is not overwritten on each call. See \fBrpc_clnt_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_sperror()\fR\fR +.ad +.RS 23n +.rt +Similar to \fBclnt_perror()\fR, except that like \fBclnt_sperrno()\fR, it +returns a string instead of printing to standard error. However, +\fBclnt_sperror()\fR does not append a newline at the end of the message. +.sp +\fBclnt_sperror()\fR returns a pointer to a buffer that is overwritten on each +call. In multithreaded applications, this buffer is implemented as +thread-specific data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_broadcast()\fR\fR +.ad +.RS 23n +.rt +Similar to \fBrpc_call()\fR, except that the call message is broadcast to all +the connectionless transports specified by \fInettype\fR. If \fInettype\fR is +\fINULL\fR, it defaults to \fBnetpath\fR. Each time it receives a response, +this routine calls \fBeachresult()\fR, whose form is: +.sp +.in +2 +.nf +bool_t eachresult(caddr_t out, const struct netbuf *addr, +const struct netconfig *netconf); +.fi +.in -2 + +where \fIout\fR is the same as \fIout\fR passed to \fBrpc_broadcast()\fR, +except that the remote procedure's output is decoded there. \fIaddr\fR points +to the address of the machine that sent the results, and \fInetconf\fR is the +netconfig structure of the transport on which the remote server responded. If +\fBeachresult()\fR returns \fB0\fR, \fBrpc_broadcast()\fR waits for more +replies; otherwise, it returns with appropriate status. +.sp +The broadcast file descriptors are limited in size to the maximum transfer size +of that transport. For Ethernet, this value is 1500 bytes. +\fBrpc_broadcast()\fR uses \fBAUTH_SYS\fR credentials by default. See +\fBrpc_clnt_auth\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_broadcast_exp()\fR\fR +.ad +.RS 23n +.rt +Similar to \fBrpc_broadcast()\fR, except that the initial timeout, +\fIinittime\fR and the maximum timeout, \fIwaittime\fR, are specified in +milliseconds. +.sp +\fIinittime\fR is the initial time that \fBrpc_broadcast_exp()\fR waits before +resending the request. After the first resend, the retransmission interval +increases exponentially until it exceeds \fIwaittime\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_call()\fR\fR +.ad +.RS 23n +.rt +Calls the remote procedure associated with \fIprognum\fR, \fIversnum\fR, and +\fIprocnum\fR on the machine, \fIhost\fR. The parameter \fIinproc\fR is used to +encode the procedure's parameters, and \fIoutproc\fR is used to decode the +procedure's results. \fIin\fR is the address of the procedure's argument(s), +and \fIout\fR is the address of where to place the result(s). \fInettype\fR can +be any of the values listed on \fBrpc\fR(3NSL). This routine returns +\fBRPC_SUCCESS\fR if it succeeds, or it returns an appropriate status. Use the +\fBclnt_perrno()\fR routine to translate failure status into error messages. +.sp +The \fBrpc_call()\fR function uses the first available transport belonging to +the class \fInettype\fR on which it can create a connection. You do not have +control of timeouts or authentication using this routine. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitectureAll +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBprintf\fR(3C), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), +\fBrpc_clnt_create\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_clnt_create.3nsl b/usr/src/man/man3nsl/rpc_clnt_create.3nsl new file mode 100644 index 0000000000..5ae84a9e21 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_clnt_create.3nsl @@ -0,0 +1,591 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_clnt_create 3NSL "23 Jul 2009" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_clnt_create, clnt_control, clnt_create, clnt_create_timed, +clnt_create_vers, clnt_create_vers_timed, clnt_destroy, clnt_dg_create, +clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror, clnt_tli_create, +clnt_tp_create, clnt_tp_create_timed, clnt_vc_create, rpc_createerr, +clnt_door_create \- library routines for dealing with creation and manipulation +of CLIENT handles +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpc.h> + +\fBbool_t\fR \fBclnt_control\fR(\fBCLIENT *\fR\fIclnt\fR, \fBconst uint_t\fR \fIreq\fR, \fBchar *\fR\fIinfo\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_create\fR(\fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst char *\fR\fInettype\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_create_timed\fR(\fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst\fR \fInettype\fR, + \fBconst struct timeval *\fR\fItimetout\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_create_vers\fR (\fBconst char *\fR\fIhost\fR, + \fBconst rpcprog_t\fR \fIprognum\fR, \fBrpcvers_t *\fR\fIvers_outp\fR, + \fBconst rpcvers_t\fR \fIvers_low\fR, \fBconst rpcvers_t\fR \fIvers_high\fR, + \fBconst char *\fR\fInettype\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_create_vers_timed\fR(\fBconst char *\fR\fIhost\fR, + \fBconst rpcprog_t\fR \fIprognum\fR, \fBrpcvers_t *\fR\fIvers_outp\fR, + \fBconst rpcvers_t\fR \fIvers_low\fR, \fBconst rpcvers_t\fR \fIvers_high\fR, + \fBchar *\fR\fInettype\fR, \fBconst struct timeval *\fR\fItimeout\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBclnt_destroy\fR(\fBCLIENT *\fR\fIclnt\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_dg_create\fR(\fBconst int\fR \fIfildes\fR, + \fBconst struct netbuf *\fR\fIsvcaddr\fR, \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst uint_t\fR \fIsendsz\fR, + \fBconst uint_t\fR \fIrecsz\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBclnt_pcreateerror\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_raw_create\fR(\fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBclnt_spcreateerror\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_tli_create\fR(\fBconst int\fR \fIfildes\fR, + \fBconst struct netconfig *\fR\fInetconf\fR, \fBconst struct netbuf *\fR\fIsvcaddr\fR, + \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst uint_t\fR \fIsendsz\fR, \fBconst uint_t\fR \fIrecsz\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_tp_create\fR(\fBconst char *\fR\fIhost\fR, + \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst struct netconfig *\fR\fInetconf\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_tp_create_timed\fR(\fBconst char *\fR\fIhost\fR, + \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst struct netconfig *\fR\fInetconf\fR, \fBconst struct timeval *\fR\fItimeout\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_vc_create\fR(\fBconst int\fR \fIfildes\fR, + \fBconst struct netbuf *\fR\fIsvcaddr\fR, \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst uint_t\fR \fIsendsz\fR, + \fBconst uint_t\fR \fIrecsz\fR); +.fi + +.LP +.nf +\fBstruct rpc_createerr\fR \fBrpc_createerr\fR +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnt_door_create\fR(\fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst uint_t\fR \fIsendsz\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBRPC\fR library routines allow \fBC\fR language programs to make procedure +calls on other machines across the network. First a \fBCLIENT\fR handle is +created and then the client calls a procedure to send a request to the server. +On receipt of the request, the server calls a dispatch routine to perform the +requested service, and then sends a reply. +.sp +.LP +These routines are MT-Safe. In the case of multithreaded applications, the +\fB-mt\fR option must be specified on the command line at compilation time. +When the \fB-mt\fR option is specified, \fBrpc_createerr()\fR becomes a macro +that enables each thread to have its own \fBrpc_createerr()\fR. See +\fBthreads\fR(5). +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBCLIENT\fR data structure. +.sp +.ne 2 +.mk +.na +\fB\fBclnt_control()\fR\fR +.ad +.sp .6 +.RS 4n +A function macro to change or retrieve various information about a client +object. \fIreq\fR indicates the type of operation, and \fIinfo\fR is a pointer +to the information. For both connectionless and connection-oriented transports, +the supported values of \fIreq\fR and their argument types and what they do +are: +.sp +.in +2 +.nf +CLSET_TIMEOUT struct timeval * set total timeout +CLGET_TIMEOUT struct timeval * get total timeout +.fi +.in -2 + +If the timeout is set using \fBclnt_control()\fR, the timeout argument passed +by \fBclnt_call()\fR is ignored in all subsequent calls. If the timeout value +is set to \fB0\fR, \fBclnt_control()\fR immediately returns +\fBRPC_TIMEDOUT\fR. Set the timeout parameter to \fB0\fR for batching calls. +.sp +.in +2 +.nf +CLGET_SERVER_ADDR struct netbuf * get server's address +CLGET_SVC_ADDR struct netbuf * get server's address +CLGET_FD int * get associated file descriptor +CLSET_FD_CLOSE void close the file descriptor when + destroying the client handle + (see \fBclnt_destroy()\fR) +CLSET_FD_NCLOSE void do not close the file + descriptor when destroying the client handle +CLGET_VERS rpcvers_t get the RPC program's version + number associated with the + client handle +CLSET_VERS rpcvers_t set the RPC program's version + number associated with the + client handle. This assumes + that the RPC server for this + new version is still listening + at the address of the previous + version. +CLGET_XID uint32_t get the XID of the previous + remote procedure call +CLSET_XID uint32_t set the XID of the next + remote procedure call +CLGET_PROG rpcprog_t get program number +CLSET_PROG rpcprog_t set program number +.fi +.in -2 + +The following operations are valid for connection-oriented transports only: +.sp +.in +2 +.nf +CLSET_IO_MODE rpciomode_t* set the IO mode used + to send one-way requests. The argument for this operation + can be either: + - RPC_CL_BLOCKING all sending operations block + until the underlying transport protocol has + accepted requests. If you specify this argument + you cannot use flush and getting and setting buffer + size is meaningless. + - RPC_CL_NONBLOCKING sending operations do not + block and return as soon as requests enter the buffer. + You can now use non-blocking I/O. The requests in the + buffer are pending. The requests are sent to + the server as soon as a two-way request is sent + or a flush is done. You are responsible for flushing + the buffer. When you choose RPC_CL_NONBLOCKING argument + you have a choice of flush modes as specified by + CLSET_FLUSH_MODE. +CLGET_IO_MODE rpciomode_t* get the current IO mode +CLSET_FLUSH_MODE rpcflushmode_t* set the flush mode. + The flush mode can only be used in non-blocking I/O mode. + The argument can be either of the following: + - RPC_CL_BESTEFFORT_FLUSH: All flushes send requests + in the buffer until the transport end-point blocks. + If the transport connection is congested, the call + returns directly. + - RPC_CL_BLOCKING_FLUSH: Flush blocks until the + underlying transport protocol accepts all pending + requests into the queue. +CLGET_FLUSH_MODE rpcflushmode_t* get the current flush mode. +CLFLUSH rpcflushmode_t flush the pending requests. + This command can only be used in non-blocking I/O mode. + The flush policy depends on which of the following + parameters is specified: + - RPC_CL_DEFAULT_FLUSH, or NULL: The flush is done + according to the current flush mode policy + (see CLSET_FLUSH_MODE option). + - RPC_CL_BESTEFFORT_FLUSH: The flush tries + to send pending requests without blocking; the call + returns directly. If the transport connection is + congested, this call could return without the request + being sent. + - RPC_CL_BLOCKING_FLUSH: The flush sends all pending + requests. This call will block until all the requests + have been accepted by the transport layer. +CLSET_CONNMAXREC_SIZE int* set the buffer size. + It is not possible to dynamically + resize the buffer if it contains data. + The default size of the buffer is 16 kilobytes. +CLGET_CONNMAXREC_SIZE int* get the current size of the + buffer +CLGET_CURRENT_REC_SIZE int* get the size of + the pending requests stored in the buffer. Use of this + command is only recommended when you are in non-blocking + I/O mode. The current size of the buffer is always zero + when the handle is in blocking mode as the buffer is not + used in this mode. +.fi +.in -2 + +The following operations are valid for connectionless transports only: +.sp +.in +2 +.nf +CLSET_RETRY_TIMEOUT struct timeval * set the retry timeout +CLGET_RETRY_TIMEOUT struct timeval * get the retry timeout +.fi +.in -2 + +The retry timeout is the time that \fBRPC\fR waits for the server to reply +before retransmitting the request. +.sp +\fBclnt_control()\fR returns \fBTRUE\fR on success and \fBFALSE\fR on failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_create()\fR\fR +.ad +.sp .6 +.RS 4n +Generic client creation routine for program \fIprognum\fR and version +\fIversnum\fR. \fIhost\fR identifies the name of the remote host where the +server is located. \fInettype\fR indicates the class of transport protocol to +use. The transports are tried in left to right order in \fBNETPATH\fR variable +or in top to bottom order in the netconfig database. +.sp +\fBclnt_create()\fR tries all the transports of the \fInettype\fR class +available from the \fBNETPATH\fR environment variable and the netconfig +database, and chooses the first successful one. A default timeout is set and +can be modified using \fBclnt_control()\fR. This routine returns \fINULL\fR if +it fails. The \fBclnt_pcreateerror()\fR routine can be used to print the reason +for failure. +.sp +Note that \fBclnt_create()\fR returns a valid client handle even if the +particular version number supplied to \fBclnt_create()\fR is not registered +with the \fBrpcbind\fR service. This mismatch will be discovered by a +\fBclnt_call\fR later (see \fBrpc_clnt_calls\fR(3NSL)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_create_timed()\fR\fR +.ad +.sp .6 +.RS 4n +Generic client creation routine which is similar to \fBclnt_create()\fR but +which also has the additional parameter \fItimeout\fR that specifies the +maximum amount of time allowed for each transport class tried. In all other +respects, the \fBclnt_create_timed()\fR call behaves exactly like the +\fBclnt_create()\fR call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_create_vers()\fR\fR +.ad +.sp .6 +.RS 4n +Generic client creation routine which is similar to \fBclnt_create()\fR but +which also checks for the version availability. \fIhost\fR identifies the name +of the remote host where the server is located. \fInettype\fR indicates the +class transport protocols to be used. If the routine is successful it returns a +client handle created for the highest version between \fIvers_low\fR and +\fIvers_high\fR that is supported by the server. \fIvers_outp\fR is set to this +value. That is, after a successful return \fIvers_low\fR <= \fI*vers_outp\fR <= +\fIvers_high\fR. If no version between \fIvers_low\fR and \fIvers_high\fR is +supported by the server then the routine fails and returns \fBNULL.\fR A +default timeout is set and can be modified using \fBclnt_control()\fR. This +routine returns \fINULL\fR if it fails. The \fBclnt_pcreateerror()\fR routine +can be used to print the reason for failure. +.sp +Note: \fBclnt_create()\fR returns a valid client handle even if the particular +version number supplied to \fBclnt_create()\fR is not registered with the +\fBrpcbind\fR service. This mismatch will be discovered by a \fBclnt_call\fR +later (see \fBrpc_clnt_calls\fR(3NSL)). However, \fBclnt_create_vers()\fR does +this for you and returns a valid handle only if a version within the range +supplied is supported by the server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_create_vers_timed()\fR\fR +.ad +.sp .6 +.RS 4n +Generic client creation routine similar to \fBclnt_create_vers()\fR but with +the additional parameter \fItimeout\fR, which specifies the maximum amount of +time allowed for each transport class tried. In all other respects, the +\fBclnt_create_vers_timed()\fR call behaves exactly like the +\fBclnt_create_vers()\fR call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_destroy()\fR\fR +.ad +.sp .6 +.RS 4n +A function macro that destroys the client's \fBRPC\fR handle. Destruction +usually involves deallocation of private data structures, including \fIclnt\fR +itself. Use of \fIclnt\fR is undefined after calling \fBclnt_destroy()\fR. If +the \fBRPC\fR library opened the associated file descriptor, or +\fBCLSET_FD_CLOSE\fR was set using \fBclnt_control()\fR, the file descriptor +will be closed. +.sp +The caller should call \fBauth_destroy(\fR\fIclnt\fR->\fBcl_auth)\fR (before +calling \fBclnt_destroy()\fR) to destroy the associated \fBAUTH\fR structure +(see \fBrpc_clnt_auth\fR(3NSL)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_dg_create()\fR\fR +.ad +.sp .6 +.RS 4n +This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR +and version \fIversnum\fR; the client uses a connectionless transport. The +remote program is located at address \fIsvcaddr\fR. The parameter \fIfildes\fR +is an open and bound file descriptor. This routine will resend the call message +in intervals of 15 seconds until a response is received or until the call times +out. The total time for the call to time out is specified by \fBclnt_call()\fR +(see \fBclnt_call()\fR in \fBrpc_clnt_calls\fR(3NSL)). The retry time out and +the total time out periods can be changed using \fBclnt_control()\fR. The user +may set the size of the send and receive buffers with the parameters +\fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR choose suitable defaults. This +routine returns \fINULL\fR if it fails. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_pcreateerror()\fR\fR +.ad +.sp .6 +.RS 4n +Print a message to standard error indicating why a client \fBRPC\fR handle +could not be created. The message is prepended with the string \fIs\fR and a +colon, and appended with a newline. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_raw_create()\fR\fR +.ad +.sp .6 +.RS 4n +This routine creates an \fBRPC\fR client handle for the remote program +\fIprognum\fR and version \fIversnum\fR. The transport used to pass messages to +the service is a buffer within the process's address space, so the +corresponding \fBRPC\fR server should live in the same address space; (see +\fBsvc_raw_create()\fR in \fBrpc_svc_create\fR(3NSL)). This allows simulation +of \fBRPC\fR and measurement of \fBRPC\fR overheads, such as round trip times, +without any kernel or networking interference. This routine returns \fINULL\fR +if it fails. \fBclnt_raw_create()\fR should be called after +\fBsvc_raw_create()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_spcreateerror()\fR\fR +.ad +.sp .6 +.RS 4n +Like \fBclnt_pcreateerror()\fR, except that it returns a string instead of +printing to the standard error. A newline is not appended to the message in +this case. +.sp +Warning: returns a pointer to a buffer that is overwritten on each call. In +multithread applications, this buffer is implemented as thread-specific data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_tli_create()\fR\fR +.ad +.sp .6 +.RS 4n +This routine creates an \fBRPC\fR client handle for the remote program +\fIprognum\fR and version \fIversnum\fR. The remote program is located at +address \fIsvcaddr\fR. If \fIsvcaddr\fR is \fINULL\fR and it is +connection-oriented, it is assumed that the file descriptor is connected. For +connectionless transports, if \fIsvcaddr\fR is \fINULL\fR, +\fBRPC_UNKNOWNADDR\fR error is set. \fIfildes\fR is a file descriptor which may +be open, bound and connected. If it is \fBRPC_ANYFD\fR, it opens a file +descriptor on the transport specified by \fInetconf\fR. If \fIfildes\fR is +\fBRPC_ANYFD\fR and \fInetconf\fR is \fINULL\fR, a \fBRPC_UNKNOWNPROTO\fR error +is set. If \fIfildes\fR is unbound, then it will attempt to bind the +descriptor. The user may specify the size of the buffers with the parameters +\fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR choose suitable defaults. +Depending upon the type of the transport (connection-oriented or +connectionless), \fBclnt_tli_create()\fR calls appropriate client creation +routines. This routine returns \fINULL\fR if it fails. The +\fBclnt_pcreateerror()\fR routine can be used to print the reason for failure. +The remote \fBrpcbind\fR service (see \fBrpcbind\fR(1M)) is not consulted for +the address of the remote service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_tp_create()\fR\fR +.ad +.sp .6 +.RS 4n +Like \fBclnt_create()\fR except \fBclnt_tp_create()\fR tries only one transport +specified through \fInetconf\fR. +.sp +\fBclnt_tp_create()\fR creates a client handle for the program \fIprognum\fR, +the version \fIversnum\fR, and for the transport specified by \fInetconf\fR. +Default options are set, which can be changed using \fBclnt_control()\fR calls. +The remote \fBrpcbind\fR service on the host \fIhost\fR is consulted for the +address of the remote service. This routine returns \fINULL\fR if it fails. The +\fBclnt_pcreateerror()\fR routine can be used to print the reason for failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_tp_create_timed()\fR\fR +.ad +.sp .6 +.RS 4n +Like \fBclnt_tp_create()\fR except \fBclnt_tp_create_timed()\fR has the extra +parameter \fItimeout\fR which specifies the maximum time allowed for the +creation attempt to succeed. In all other respects, the +\fBclnt_tp_create_timed()\fR call behaves exactly like the +\fBclnt_tp_create()\fR call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_vc_create()\fR\fR +.ad +.sp .6 +.RS 4n +This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR +and version \fIversnum\fR; the client uses a connection-oriented transport. The +remote program is located at address \fIsvcaddr\fR. The parameter \fIfildes\fR +is an open and bound file descriptor. The user may specify the size of the send +and receive buffers with the parameters \fIsendsz\fR and \fIrecvsz\fR; values +of \fB0\fR choose suitable defaults. This routine returns \fINULL\fR if it +fails. +.sp +The address \fIsvcaddr\fR should not be \fINULL\fR and should point to the +actual address of the remote program. \fBclnt_vc_create()\fR does not consult +the remote \fBrpcbind\fR service for this information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_createerr()\fR\fR +.ad +.sp .6 +.RS 4n +A global variable whose value is set by any \fBRPC\fR client handle creation +routine that fails. It is used by the routine \fBclnt_pcreateerror()\fR to +print the reason for the failure. +.sp +In multithreaded applications, \fBrpc_createerr\fR becomes a macro which +enables each thread to have its own \fBrpc_createerr\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_door_create()\fR\fR +.ad +.sp .6 +.RS 4n +This routine creates an RPC client handle over doors for the given program +\fIprognum\fR and version \fIversnum\fR. Doors is a transport mechanism that +facilitates fast data transfer between processes on the same machine. The user +may set the size of the send buffer with the parameter \fIsendsz\fR. If +\fIsendsz\fR is 0, the corresponding default buffer size is 16 Kbyte. The +\fBclnt_door_create()\fR routine returns \fINULL\fR if it fails and sets a +value for \fBrpc_createerr\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitectureAll +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), +\fBrpc_clnt_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL), +\fBsvc_raw_create\fR(3NSL), \fBthreads\fR(5), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_control.3nsl b/usr/src/man/man3nsl/rpc_control.3nsl new file mode 100644 index 0000000000..645223607a --- /dev/null +++ b/usr/src/man/man3nsl/rpc_control.3nsl @@ -0,0 +1,138 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_control 3NSL "24 Feb 1999" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_control \- library routine for manipulating global RPC attributes for +client and server applications +.SH SYNOPSIS +.LP +.nf +\fBbool_t\fR \fBrpc_control\fR(\fBint\fR \fIop\fR, \fBvoid *\fR\fIinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This \fBRPC\fR library routine allows applications to set and modify global +\fBRPC\fR attributes that apply to clients as well as servers. At present, it +supports only server side operations. This function allows applications to set +and modify global attributes that apply to client as well as server functions. +\fIop\fR indicates the type of operation, and \fIinfo\fR is a pointer to the +operation specific information. The supported values of \fIop\fR and their +argument types, and what they do are: +.sp +.in +2 +.nf +RPC_SVC_MTMODE_SET int * set multithread mode +RPC_SVC_MTMODE_GET int * get multithread mode +RPC_SVC_THRMAX_SET int * set maximum number of threads +RPC_SVC_THRMAX_GET int * get maximum number of threads +RPC_SVC_THRTOTAL_GET int * get number of active threads +RPC_SVC_THRCREATES_GET int * get number of threads created +RPC_SVC_THRERRORS_GET int * get number of thread create errors +RPC_SVC_USE_POLLFD int * set number of file descriptors to unlimited +RPC_SVC_CONNMAXREC_SET int * set non-blocking max rec size +RPC_SVC_CONNMAXREC_GET int * get non-blocking max rec size +.fi +.in -2 + +.sp +.LP +There are three multithread (MT) modes. These are: +.sp +.in +2 +.nf +RPC_SVC_MT_NONE Single threaded mode (default) +RPC_SVC_MT_AUTO Automatic MT mode +RPC_SVC_MT_USER User MT mode +.fi +.in -2 + +.sp +.LP +Unless the application sets the Automatic or User MT modes, it will stay in the +default (single threaded) mode. See the \fINetwork Interfaces Programmer's +Guide\fR for the meanings of these modes and programming examples. Once a mode +is set, it cannot be changed. +.sp +.LP +By default, the maximum number of threads that the server will create at any +time is 16. This allows the service developer to put a bound on thread +resources consumed by a server. If a server needs to process more than 16 +client requests concurrently, the maximum number of threads must be set to the +desired number. This parameter may be set at any time by the server. +.sp +.LP +Set and get operations will succeed even in modes where the operations don't +apply. For example, you can set the maximum number of threads in any mode, +even though it makes sense only for the Automatic MT mode. All of the get +operations except \fBRPC_SVC_MTMODE_GET\fR apply only to the Automatic MT mode, +so values returned in other modes may be undefined. +.sp +.LP +By default, \fBRPC\fR servers are limited to a maximum of 1024 file descriptors +or connections due to limitations in the historical interfaces +\fBsvc_fdset\fR(3NSL) and \fBsvc_getreqset\fR(3NSL). Applications written to +use the preferred interfaces of \fBsvc_pollfd\fR(3NSL) and +\fBsvc_getreq_poll\fR(3NSL) can use an unlimited number of file descriptors. +Setting \fBinfo\fR to point to a non-zero integer and \fIop\fR to +\fBRPC_SVC_USE_POLLFD\fR removes the limitation. +.sp +.LP +Connection oriented \fBRPC\fR transports read \fBRPC\fR requests in blocking +mode by default. Thus, they may be adversely affected by network delays and +broken clients. \fBRPC_SVC_CONNMAXREC_SET\fR enables non-blocking mode and +establishes the maximum record size (in bytes) for \fBRPC\fR requests; +\fBRPC\fR responses are not affected. Buffer space is allocated as needed up to +the specified maximum, starting at the maximum or \fBRPC_MAXDATASIZE\fR, +whichever is smaller. +.sp +.LP +The value established by \fBRPC_SVC_CONNMAXREC_SET\fR is used when a connection +is created, and it remains in effect for that connection until it is closed. To +change the value for existing connections on a per-connection basis, see +\fBsvc_control\fR(3NSL). +.sp +.LP +\fBRPC_SVC_CONNMAXREC_GET\fR retrieves the current maximum record size. A zero +value means that no maximum is in effect, and that the connections are in +blocking mode. +.sp +.LP +\fIinfo\fR is a pointer to an argument of type \fBint\fR. Non-connection RPC +transports ignore \fBRPC_SVC_CONNMAXREC_SET\fR and +\fBRPC_SVC_CONNMAXREC_GET\fR. +.SH RETURN VALUES +.sp +.LP +This routine returns \fBTRUE\fR if the operation was successful and +returns\fBFALSE\fR otherwise. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_svc_calls\fR(3NSL), +\fBattributes\fR(5) +.sp +.LP +\fINetwork Interfaces Programmer's Guide\fR diff --git a/usr/src/man/man3nsl/rpc_gss_get_error.3nsl b/usr/src/man/man3nsl/rpc_gss_get_error.3nsl new file mode 100644 index 0000000000..abb03d388e --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_get_error.3nsl @@ -0,0 +1,100 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_get_error 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_get_error \- get error codes on failure +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_get_error\fR(\fBrpc_gss_error_t\fR\fI*error\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBrpc_gss_get_error()\fR fetches an error code when an \fBRPCSEC_GSS\fR +routine fails. +.sp +.LP +\fBrpc_gss_get_error()\fR uses a \fBrpc_gss_error_t\fR structure of the +following form: +.sp +.in +2 +.nf +typedef struct { +int rpc_gss_error; \fIRPCSEC_GSS error\fR +int system_error; \fIsystem error\fR +} rpc_gss_error_t; +.fi +.in -2 + +.sp +.LP +Currently the only error codes defined for this function are +.sp +.in +2 +.nf +#define RPC_GSS_ER_SUCCESS 0 /* no error */ +#define RPC_GSS_ER_SYSTEMERROR 1 /* system error */ +.fi +.in -2 + +.SH PARAMETERS +.sp +.LP +Information on \fBRPCSEC_GSS\fR data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fBerror\fR \fR +.ad +.RS 10n +.rt +A \fBrpc_gss_error_t\fR structure. If the \fBrpc_gss_error\fR field is equal +to \fBRPC_GSS_ER_SYSTEMERROR,\fR the \fBsystem_error\fR field will be set to +the value of \fBerrno\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +Unless there is a failure indication from an invoked \fBRPCSEC_GSS\fR function, +\fBrpc_gss_get_error()\fR does not set \fBerror\fR to a meaningful value. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBperror\fR(3C), \fBrpc\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. +.SH NOTES +.sp +.LP +Only system errors are currently returned. diff --git a/usr/src/man/man3nsl/rpc_gss_get_mechanisms.3nsl b/usr/src/man/man3nsl/rpc_gss_get_mechanisms.3nsl new file mode 100644 index 0000000000..4dabc40a8f --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_get_mechanisms.3nsl @@ -0,0 +1,188 @@ +'\" te +.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_get_mechanisms 3NSL "29 Jun 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_get_mechanisms, rpc_gss_get_mech_info, rpc_gss_get_versions, +rpc_gss_is_installed \- get information on mechanisms and RPC version +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBchar **\fR\fBrpc_gss_get_mechanisms\fR(\fB\fR\fI\fR); +.fi + +.LP +.nf +\fBchar **\fR\fBrpc_gss_get_mech_info\fR(\fBchar *\fR\fImech\fR, \fBrpc_gss_service_t *\fR\fIservice\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBrpc_gss_get_versions\fR(\fBu_int *\fR\fIvers_hi\fR, \fBu_int *\fR\fIvers_lo\fR); +.fi + +.LP +.nf +\fBbool_t rpc_gss_is\fR \fBinstalled\fR(\fBchar *\fR\fImech\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These "convenience functions" return information on available security +mechanisms and versions of \fBRPCSEC_GSS\fR . +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_mechanisms()\fR \fR +.ad +.RS 29n +.rt +Returns a list of supported security mechanisms as a null-terminated list of +character strings. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_mech_info()\fR \fR +.ad +.RS 29n +.rt +Takes two arguments: an ASCII string representing a mechanism type, for +example, \fBkerberosv5\fR, and a pointer to a \fBrpc_gss_service_t\fR enum. +\fBrpc_gss_get_mech_info()\fR will return \fBNULL\fR upon error or if no +\fB/etc/gss/qop\fR file is present. Otherwise, it returns a null-terminated +list of character strings of supported Quality of Protections (QOPs) for this +mechanism. \fBNULL\fR or empty list implies only that the default QOP is +available and can be specified to routines that need to take a QOP string +parameter as NULL or as an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_versions()\fR \fR +.ad +.RS 29n +.rt +Returns the highest and lowest versions of \fBRPCSEC_GSS\fR supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_is_installed()\fR \fR +.ad +.RS 29n +.rt +Takes an ASCII string representing a mechanism, and returns \fBTRUE\fR if the +mechanism is installed. +.RE + +.SH PARAMETERS +.sp +.LP +Information on \fBRPCSEC_GSS\fR data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fImech\fR \fR +.ad +.RS 12n +.rt +An ASCII string representing the security mechanism in use. Valid strings may +also be found in the \fB/etc/gss/mech\fR file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIservice\fR \fR +.ad +.RS 12n +.rt +A pointer to a \fBrpc_gss_service_t\fR enum, representing the current security +service (privacy, integrity, or none). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvers_hi\fR\fR +.ad +.br +.na +\fB\fIvers_lo\fR \fR +.ad +.RS 12n +.rt +The highest and lowest versions of \fBRPCSEC_GSS\fR supported. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/mech\fR \fR +.ad +.RS 18n +.rt +File containing valid security mechanisms +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/qop\fR \fR +.ad +.RS 18n +.rt +File containing valid QOP values +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL),\fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \fBqop\fR(4), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2743, Generic Security Service Application Program Interface Version 2, Update 1\fR. Network Working Group. January 2000. +.SH NOTES +.sp +.LP +This function will change in a future release. diff --git a/usr/src/man/man3nsl/rpc_gss_get_principal_name.3nsl b/usr/src/man/man3nsl/rpc_gss_get_principal_name.3nsl new file mode 100644 index 0000000000..8e49ed1159 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_get_principal_name.3nsl @@ -0,0 +1,156 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_get_principal_name 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_get_principal_name \- Get principal names at server +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_get_principal_name\fR(\fBrpc_gss_principal_\fR \fI*principal\fR, + \fBchar\fR \fI*mech\fR, \fBchar\fR \fI*name\fR, \fBchar\fR \fI*node\fR, \fBchar\fR \fI*domain\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Servers need to be able to operate on a client's principal name. Such a name is +stored by the server as a \fBrpc_gss_principal_t\fR structure, an opaque byte +string which can be used either directly in access control lists or as database +indices which can be used to look up a UNIX credential. A server may, for +example, need to compare a principal name it has received with the principal +name of a known entity, and to do that, it must be able to generate +\fBrpc_gss_principal_t\fR structures from known entities. +.sp +.LP +\fBrpc_gss_get_principal_name()\fR takes as input a security mechanism, a +pointer to a \fBrpc_gss_principal_t\fR structure, and several parameters which +uniquely identify an entity on a network: a user or service name, a node name, +and a domain name. From these parameters it constructs a unique, +mechanism-dependent principal name of the \fBrpc_gss_principal_t\fR structure +type. +.SH PARAMETERS +.sp +.LP +How many of the identifying parameters (\fIname \fR, \fInode\fR, and \fI +\fRdomain\fI)\fR are necessary to specify depends on the mechanism being used. +For example, Kerberos V5 requires only a user name but can accept a node and +domain name. An application can choose to set unneeded parameters to +\fINULL.\fR +.sp +.LP +Information on RPCSEC_GSS data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fIprincipal\fR \fR +.ad +.RS 14n +.rt +An opaque, mechanism-dependent structure representing the client's principal +name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImech\fR \fR +.ad +.RS 14n +.rt +An ASCII string representing the security mechanism in use. Valid strings may +be found in the \fB/etc/gss/mech\fR file, or by using +\fBrpc_gss_get_mechanisms()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR \fR +.ad +.RS 14n +.rt +A UNIX login name (for example, 'gwashington') or service name, such as 'nfs'. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInode\fR \fR +.ad +.RS 14n +.rt +A node in a domain; typically, this would be a machine name (for +example, 'valleyforge'). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdomain\fR \fR +.ad +.RS 14n +.rt +A security domain; for example, a DNS, NIS, or NIS+ domain name +('eng.company.com'). +.RE + +.SH RETURN VALUES +.sp +.LP +\fBrpc_gss_get_principal_name()\fR returns TRUE if it is successful; +otherwise, use \fBrpc_gss_get_error()\fR to get the error associated with the +failure. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/mech\fR \fR +.ad +.RS 18n +.rt +File containing valid security mechanisms +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBfree\fR(3C), \fBrpc\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL), \fBrpc_gss_set_svc_name\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. +.SH NOTES +.sp +.LP +Principal names may be freed up by a call to \fBfree\fR(3C). A principal name need only be freed in those instances where it was constructed by the application. (Values returned by other routines point to structures already existing in a context, and need not be freed.) diff --git a/usr/src/man/man3nsl/rpc_gss_getcred.3nsl b/usr/src/man/man3nsl/rpc_gss_getcred.3nsl new file mode 100644 index 0000000000..f4616f8e31 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_getcred.3nsl @@ -0,0 +1,125 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_getcred 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_getcred \- get credentials of client +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_getcred\fR(\fBstruct svc_req\fR \fI*req\fR, \fBrpc_gss_rawcred_ t\fR \fI**rcred\fR, + \fBrpc_gss_ucred\fR \fI**ucred\fR, \fBvoid\fR \fI**cookie\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBrpc_gss_getcred()\fR is used by a server to fetch the credentials of a +client. These credentials may either be network credentials (in the form of a +\fBrpc_gss_rawcred_t\fR structure) or UNIX credentials. +.sp +.LP +For more information on \fBRPCSEC_GSS\fR data types, see the +\fBrpcsec_gss\fR(3NSL) man page. +.SH PARAMETERS +.sp +.LP +Essentially, \fBrpc_gss_getcred()\fR passes a pointer to a request +(\fBsvc_req\fR) as well as pointers to two credential structures and a +user-defined cookie; if \fBrpc_gss_getcred()\fR is successful, at least one +credential structure is "filled out" with values, as is, optionally, the +cookie. +.sp +.ne 2 +.mk +.na +\fB\fIreq\fR \fR +.ad +.RS 11n +.rt +Pointer to the received service request. \fBsvc_req\fR is an RPC structure +containing information on the context of an RPC invocation, such as program, +version, and transport information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrcred\fR \fR +.ad +.RS 11n +.rt +A pointer to an \fBrpc_gss_rawcred_t\fR structure pointer. This structure +contains the version number of the \fBRPCSEC_GSS\fR protocol being used; the +security mechanism and QOPs for this session (as strings); principal names for +the client (as a \fBrpc_gss_principal_t\fR structure) and server (as a string); +and the security service (integrity, privacy, etc., as an enum). If an +application is not interested in these values, it may pass \fINULL\fR for this +parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIucred\fR \fR +.ad +.RS 11n +.rt +The caller's UNIX credentials, in the form of a pointer to a pointer to a +\fBrpc_gss_ucred_t\fR structure, which includes the client's uid and gids. If +an application is not interested in these values, it may pass \fINULL\fR for +this parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookie\fR \fR +.ad +.RS 11n +.rt +A four-byte quantity that an application may use in any manner it wants to; RPC +does not interpret it. (For example, a cookie may be a pointer or index to a +structure that represents a context initiator.) See also +\fBrpc_gss_set_callback\fR(3NSL). +.RE + +.SH RETURN VALUES +.sp +.LP +\fBrpc_gss_getcred()\fR returns TRUE if it is successful; otherwise, use +\fBrpc_gss_get_error()\fR to get the error associated with the failure. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_gss_set_callback\fR(3NSL), \fBrpc_gss_set_svc_name\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. diff --git a/usr/src/man/man3nsl/rpc_gss_max_data_length.3nsl b/usr/src/man/man3nsl/rpc_gss_max_data_length.3nsl new file mode 100644 index 0000000000..f89587ba8a --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_max_data_length.3nsl @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_max_data_length 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_max_data_length, rpc_gss_svc_max_data_length \- get maximum data length +for transmission +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBint\fR \fBrpc_gss_max_data_length\fR(\fBAUTH\fR \fI*handle\fR, \fBint\fR \fImax_tp_unit_len\fR); +.fi + +.LP +.nf +\fBint\fR \fBrpc_gss_svc_max_data_length\fR(\fBstruct svc_req\fR \fI*req\fR, \fBint\fR \fImax_tp_unit_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Performing a security transformation on a piece of data generally produces +data with a different (usually greater) length. For some transports, such as +UDP, there is a maximum length of data which can be sent out in one data unit. +Applications need to know the maximum size a piece of data can be before it's +transformed, so that the resulting data will still "fit" on the transport. +These two functions return that maximum size. +.sp +.LP +\fBrpc_gss_max_data_length()\fR is the client-side version; +\fBrpc_gss_svc_max_data_length()\fR is the server-side version. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 20n +.rt +An RPC context handle of type \fBAUTH,\fR returned when a context is created +(for example, by \fBrpc_gss_seccreate()\fR. Security service and QOP are bound +to this handle, eliminating any need to specify them. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImax_tp_unit_len\fR \fR +.ad +.RS 20n +.rt +The maximum size of a piece of data allowed by the transport. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreq\fR \fR +.ad +.RS 20n +.rt +A pointer to an RPC \fBsvc_req\fR structure, containing information on the +context (for example, program number and credentials). +.RE + +.SH RETURN VALUES +.sp +.LP +Both functions return the maximum size of untransformed data allowed, as an +\fBint\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. diff --git a/usr/src/man/man3nsl/rpc_gss_mech_to_oid.3nsl b/usr/src/man/man3nsl/rpc_gss_mech_to_oid.3nsl new file mode 100644 index 0000000000..64714479eb --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_mech_to_oid.3nsl @@ -0,0 +1,142 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_mech_to_oid 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_mech_to_oid, rpc_gss_qop_to_num \- map mechanism, QOP strings to +non-string values +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_mech_to_oid\fR(\fBcharc\fR\fI*mech\fR, \fBrpc_gss_OIDc\fR\fI*oid\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBrpc_gss_qop_to_num\fR(\fBchar\fR \fI*qop\fR, \fBchar\fR \fI*mech\fR, \fBu_int\fR \fI*num\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Because in-kernel RPC routines use non-string values for mechanism and Quality +of Protection (QOP), these routines exist to map strings for these attributes +to their non-string counterparts. (The non-string values for QOP and +mechanism are also found in the \fB/etc/gss/qop\fR and \fB/etc/gss/mech\fR +files, respectively.) \fBrpc_gss_mech_to_oid()\fR takes a string representing a +mechanism, as well as a pointer to a \fBrpc_gss_OID\fR object identifier +structure. It then gives this structure values corresponding to the indicated +mechanism, so that the application can now use the OID directly with RPC +routines. \fBrpc_gss_qop_to_num()\fR does much the same thing, taking strings +for QOP and mechanism and returning a number. +.SH PARAMETERS +.sp +.LP +Information on \fBRPCSEC_GSS\fR data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fImech\fR \fR +.ad +.RS 9n +.rt +An ASCII string representing the security mechanism in use. Valid strings may +be found in the \fB/etc/gss/mech\fR file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoid\fR \fR +.ad +.RS 9n +.rt +An object identifier of type \fBrpc_gss_OID\fR, whose elements are usable by +kernel-level RPC routines. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIqop\fR \fR +.ad +.RS 9n +.rt +This is an ASCII string which sets the quality of protection (QOP) for the +session. Appropriate values for this string may be found in the file +\fB/etc/gss/qop\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum\fR \fR +.ad +.RS 9n +.rt +The non-string value for the QOP. +.RE + +.SH RETURN VALUES +.sp +.LP +Both functions return TRUE if they are successful, FALSE otherwise. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/mech\fR \fR +.ad +.RS 18n +.rt +File containing valid security mechanisms +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/qop\fR \fR +.ad +.RS 18n +.rt +File containing valid QOP values +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_gss_get_error\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \fBqop\fR(4), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. diff --git a/usr/src/man/man3nsl/rpc_gss_seccreate.3nsl b/usr/src/man/man3nsl/rpc_gss_seccreate.3nsl new file mode 100644 index 0000000000..9974f74e68 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_seccreate.3nsl @@ -0,0 +1,186 @@ +'\" te +.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_seccreate 3NSL "29 Jun 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_seccreate \- create a security context using the RPCSEC_GSS protocol +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBAUTH *\fR\fBrpc_gss_seccreate\fR(\fBCLIENT\fR \fI*clnt\fR, \fBchar\fR \fI*principal\fR, \fBchar\fR \fI*mechanism\fR, + \fBrpc_gss_service_t\fR \fIservice_type\fR, \fBchar\fR \fI*qop\fR, + \fBrpc_gss_options_req_t\fR \fI*options_req\fR, + \fBrpc_gss_options_ret_t\fR \fI*options_ret\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBrpc_gss_seccreate()\fR is used by an appliction to create a security context +using the \fBRPCSEC_GSS\fR protocol, making use of the underlying \fBGSS-API\fR +network layer. \fBrpc_gss_seccreate()\fR allows an application to specify the +type of security mechanism (for example, Kerberos v5), the type of service (for +example, integrity checking), and the Quality of Protection (\fBQOP\fR) desired +for transferring data. +.SH PARAMETERS +.sp +.LP +Information on \fBRPCSEC_GSS\fR data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fIclnt\fR\fR +.ad +.RS 16n +.rt +This is the RPC client handle. \fIclnt\fR may be obtained, for example, from +\fBclnt_create()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprincipal\fR\fR +.ad +.RS 16n +.rt +This is the identity of the server principal, specified in the form +\fIservice\fR@\fIhost\fR, where \fIservice\fR is the name of the service the +client wishes to access and \fIhost\fR is the fully qualified name of the host +where the service resides \(em for example, nfs@mymachine.eng.company.com. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImechanism\fR\fR +.ad +.RS 16n +.rt +This is an ASCII string which indicates which security mechanism to use with +this data. Appropriate mechanisms may be found in the file +\fB/etc/gss/mech\fR; additionally, \fBrpc_gss_get_mechanisms()\fR returns a +list of supported security mechanisms (as null-terminated strings). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIservice_type\fR\fR +.ad +.RS 16n +.rt +This sets the initial type of service for the session \(em privacy, integrity, +authentication, or none. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIqop\fR\fR +.ad +.RS 16n +.rt +This is an ASCII string which sets the quality of protection (QOP) for the +session. Appropriate values for this string may be found in the file +\fB/etc/gss/qop\fR. Additionally, supported QOPs are returned (as +null-terminated strings) by \fBrpc_gss_get_mech_info()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoptions_req\fR\fR +.ad +.RS 16n +.rt +This structure contains options which are passed directly to the underlying +\fBGSS_API\fR layer. If the caller specifies \fINULL\fR for this parameter, +defaults are used. (See \fBNOTES\fR, below.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoptions_ret\fR\fR +.ad +.RS 16n +.rt +These \fBGSS-API\fR options are returned to the caller. If the caller does not +need to see these options, then it may specify \fINULL\fR for this parameter. +(See \fBNOTES,\fR below.) +.RE + +.SH RETURN VALUES +.sp +.LP +\fBrpc_gss_seccreate()\fR returns a security context handle (an RPC +authentication handle) of type \fBAUTH\fR. If \fBrpc_gss_seccreate()\fR cannot +return successfully, the application can get an error number by calling +\fBrpc_gss_get_error()\fR. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/mech\fR\fR +.ad +.RS 17n +.rt +File containing valid security mechanisms +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/qop\fR\fR +.ad +.RS 17n +.rt +File containing valid QOP values. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBauth_destroy\fR(3NSL), \fBrpc\fR(3NSL), \fBrpc_gss_get_error\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \fBqop\fR(4), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2743, Generic Security Service Application Program Interface Version 2, Update 1\fR. Network Working Group. January 2000. +.SH NOTES +.sp +.LP +Contexts may be destroyed normally, with \fBauth_destroy()\fR. See \fBauth_destroy\fR(3NSL) diff --git a/usr/src/man/man3nsl/rpc_gss_set_callback.3nsl b/usr/src/man/man3nsl/rpc_gss_set_callback.3nsl new file mode 100644 index 0000000000..7405df9dfa --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_set_callback.3nsl @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_set_callback 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_set_callback \- specify callback for context +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_set_callback\fR(\fBstruct rpc_gss_callback_t\fR \fI*cb\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +A server may want to specify a callback routine so that it knows when a context +gets first used. This user-defined callback may be specified through the +\fBrpc_gss_set_callback()\fR routine. The callback routine is invoked the +first time a context is used for data exchanges, after the context is +established for the specified program and version. +.sp +.LP +The user-defined callback routine should take the following form: +.sp +.in +2 +.nf +bool_t callback(struct svc_req\fI *req\fR, gss_cred_id_t\fI deleg\fR, + gss_ctx_id_t\fI gss_context\fR, rpc_gss_lock_t\fI *lock\fR, void\fI **cookie\fR); +.fi +.in -2 + +.SH PARAMETERS +.sp +.LP +\fBrpc_gss_set_callback()\fR takes one argument: a pointer to a +\fBrpc_gss_callback_t\fR structure. This structure contains the RPC program +and version number as well as a pointer to a user-defined \fBcallback()\fR +routine. (For a description of \fBrpc_gss_callback_t\fR and other +\fBRPCSEC_GSS\fR data types, see the \fBrpcsec_gss\fR(3NSL) man page.) +.sp +.LP +The user-defined \fBcallback()\fR routine itself takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIreq\fR \fR +.ad +.RS 16n +.rt +Pointer to the received service request. \fBsvc_req\fR is an RPC structure +containing information on the context of an RPC invocation, such as program, +version, and transport information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdeleg\fR \fR +.ad +.RS 16n +.rt +Delegated credentials, if any. (See \fBNOTES,\fR below.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIgss_context\fR \fR +.ad +.RS 16n +.rt +GSS context (allows server to do GSS operations on the context to test for +acceptance criteria). See \fBNOTES,\fR below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlock\fR \fR +.ad +.RS 16n +.rt +This parameter is used to enforce a particular QOP and service for a session. +This parameter points to a \fBRPCSEC_GSS\fR \fBrpc_gss_lock_t\fR structure. +When the callback is invoked, the \fBrpc_gss_lock_t.locked\fR field is set to +TRUE, thus locking the context. A locked context will reject all requests +having different values for QOP or service than those specified by the +\fBraw_cred\fR field of the \fBrpc_gss_lock_t\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookie\fR \fR +.ad +.RS 16n +.rt +A four-byte quantity that an application may use in any manner it wants to \(em +RPC does not interpret it. (For example, the cookie could be a pointer or +index to a structure that represents a context initiator.) The cookie is +returned, along with the caller's credentials, with each invocation of +\fBrpc_gss_getcred()\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBrpc_gss_set_callback()\fR returns TRUE if the use of the context is +accepted; false otherwise. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_gss_getcred\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. +.SH NOTES +.sp +.LP +If a server does not specify a callback, all incoming contexts will be accepted. +.sp +.LP +Because the \fBGSS-API\fR is not currently exposed, the \fIdeleg\fR and \fIgss_context\fR arguments are mentioned for informational purposes only, and the user-defined callback function may choose to do nothing with them. diff --git a/usr/src/man/man3nsl/rpc_gss_set_defaults.3nsl b/usr/src/man/man3nsl/rpc_gss_set_defaults.3nsl new file mode 100644 index 0000000000..5a2f3599e0 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_set_defaults.3nsl @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_set_defaults 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_set_defaults \- change service, QOP for a session +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_set_defaults\fR(\fBAUTH\fR \fI*auth\fR, \fBrpc_gss_service_t\fR \fIservice\fR, \fBchar\fR \fI*qop\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBrpc_gss_set_defaults()\fR allows an application to change the service +(privacy, integrity, authentication, or none) and Quality of Protection (QOP) +for a transfer session. New values apply to the rest of the session (unless +changed again). +.SH PARAMETERS +.sp +.LP +Information on \fBRPCSEC_GSS\fR data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fIauth\fR \fR +.ad +.RS 12n +.rt +An RPC authentication handle returned by \fBrpc_gss_seccreate()\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIservice\fR \fR +.ad +.RS 12n +.rt +An enum of type \fBrpc_gss_service_t\fR, representing one of the following +types of security service: authentication, privacy, integrity, or none. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIqop\fR \fR +.ad +.RS 12n +.rt +A string representing Quality of Protection. Valid strings may be found in the +file \fB/etc/gss/qop\fR or by using \fBrpc_gss_get_mech_info()\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBrpc_gss_set_svc_name()\fR returns TRUE if it is successful; otherwise, use +\fBrpc_gss_get_error()\fR to get the error associated with the failure. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/qop\fR \fR +.ad +.RS 17n +.rt +File containing valid QOPs +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_gss_get_mech_info\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBqop\fR(4), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. diff --git a/usr/src/man/man3nsl/rpc_gss_set_svc_name.3nsl b/usr/src/man/man3nsl/rpc_gss_set_svc_name.3nsl new file mode 100644 index 0000000000..685876b0d5 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_gss_set_svc_name.3nsl @@ -0,0 +1,134 @@ +'\" te +.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_gss_set_svc_name 3NSL "5 Feb 2002" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_gss_set_svc_name \- send a principal name to a server +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpcsec_gss.h> + +\fBbool_t\fR \fBrpc_gss_set_svc_name\fR(\fBchar\fR \fI*principal\fR, \fBchar\fR \fI*mechanism\fR, + \fBu_int\fR \fIreq_time\fR,\fBu_int\fR \fIprogram\fR, \fBu_int\fR \fIversion\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBrpc_gss_set_svc_name()\fR sets the name of a principal the server is to +represent. If a server is going to act as more than one principal, this +procedure can be invoked for every such principal. +.SH PARAMETERS +.sp +.LP +Information on \fBRPCSEC_GSS\fR data types for parameters may be found on the +\fBrpcsec_gss\fR(3NSL) man page. +.sp +.ne 2 +.mk +.na +\fB\fIprincipal\fR\fR +.ad +.RS 13n +.rt +An ASCII string representing the server's principal name, given in the form of +\fIservice\fR@\fIhost\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImech\fR\fR +.ad +.RS 13n +.rt +An \fBASCII\fR string representing the security mechanism in use. Valid +strings may be found in the \fB/etc/gss/mech\fR file, or by using +\fBrpc_gss_get_mechanisms()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreq_time\fR\fR +.ad +.RS 13n +.rt +The time, in seconds, for which a credential should be valid. Note that the +\fIreq_time\fR is a hint to the underlying mechanism. The actual time that the +credential will remain valid is mechanism dependent. In the case of kerberos +the actual time will be \fBGSS_C_INDEFINITE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprogram\fR\fR +.ad +.RS 13n +.rt +The \fBRPC\fR program number for this service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 13n +.rt +The \fBRPC\fR version number for this service. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBrpc_gss_set_svc_name()\fR returns \fBTRUE\fR if it is successful; +otherwise, use \fBrpc_gss_get_error()\fR to get the error associated with the +failure. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/mech\fR\fR +.ad +.RS 17n +.rt +File containing valid security mechanisms +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_gss_get_mechanisms\fR(3NSL), \fBrpc_gss_get_principal_name\fR(3NSL), \fBrpcsec_gss\fR(3NSL), \fBmech\fR(4), \fBattributes\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2078, Generic Security Service Application Program Interface, Version 2\fR. Network Working Group. January 1997. diff --git a/usr/src/man/man3nsl/rpc_soc.3nsl b/usr/src/man/man3nsl/rpc_soc.3nsl new file mode 100644 index 0000000000..ac85ae5dda --- /dev/null +++ b/usr/src/man/man3nsl/rpc_soc.3nsl @@ -0,0 +1,890 @@ +'\" te +.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_soc 3NSL "7 Jun 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_soc, authdes_create, authunix_create, authunix_create_default, callrpc, +clnt_broadcast, clntraw_create, clnttcp_create, clntudp_bufcreate, +clntudp_create, get_myaddress, getrpcport, pmap_getmaps, pmap_getport, +pmap_rmtcall, pmap_set, pmap_unset, registerrpc, svc_fds, svc_getcaller, +svc_getreq, svc_register, svc_unregister, svcfd_create, svcraw_create, +svctcp_create, svcudp_bufcreate, svcudp_create, xdr_authunix_parms \- obsolete +library routines for RPC +.SH SYNOPSIS +.LP +.nf +#define PORTMAP +#include <rpc/rpc.h> +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthdes_create\fR(\fBchar *\fR\fIname\fR, \fBuint_t\fR \fIwindow\fR, + \fBstruct sockaddr_in *\fR\fIsyncaddr\fR, \fBdes_block *\fR\fIckey\fR); +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthunix_create\fR(\fBchar *\fR\fIhost\fR, \fBuid_t\fR \fIuid\fR, \fBgid_t\fR \fIgid\fR, + \fBint\fR \fIgrouplen\fR, \fBgid_t *\fR\fIgidlistp\fR); +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthunix_create_default\fR(void) +.fi + +.LP +.nf +\fBcallrpc\fR(\fBchar *\fR\fIhost\fR, \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, + \fBrpcproc_t\fR \fIprocnum\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBchar *\fR\fIin\fR, + \fBxdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR); +.fi + +.LP +.nf +\fBenum\fR \fBclnt_stat_clnt_broadcast\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, + \fBrpcproc_t\fR \fIprocnum\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBchar *\fR\fIin\fR, + \fBxdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR, \fBresultproc_t\fR\fIeachresult\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclntraw_create\fR(\fBrpcproc_t\fR \fIprocnum\fR, \fBrpcvers_t\fR \fIversnum\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclnttcp_create\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, + \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, \fBint *\fR\fIfdp\fR, + \fBuint_t\fR \fIsendz\fR, \fBuint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclntudp_bufcreate\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, \fBrpcprog_t\fR \fIprognum\fR, + \fBrpcvers_t\fR \fIversnum\fR, \fBstruct timeval\fR \fIwait\fR, + \fBint *\fR\fIfdp\fR, \fBuint_t\fR \fIsendz\fR, \fBuint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBCLIENT *\fR\fBclntudp_create\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, + \fBrpcprog_t\fR \fIprognum\fR, \fBstruct timeval\fR \fIwait\fR, \fBint *\fR\fIfdp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBget_myaddress\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR); +.fi + +.LP +.nf +\fBushort\fR \fBgetrpcport\fR(\fBchar *\fR\fIhost\fR, \fBrpcprog_t\fR \fIprognum\fR, + \fBrpcvers_t\fR \fIversnum\fR, \fBrpcprot_t\fR \fIproto\fR); +.fi + +.LP +.nf +\fBstruct pmaplist *\fR\fBpmap_getmaps\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR); +.fi + +.LP +.nf +\fBushort\fR \fBpmap_getport\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, + \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, + \fBrpcprot_t\fR \fIprotocol\fR); +.fi + +.LP +.nf +\fBenum clnt_stat\fR \fBpmap_rmtcall\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, + \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, + \fBrpcproc_t\fR \fIprogcnum\fR, \fBcaddr_t\fR \fIin\fR, \fBxdrproct_t\fR \fIinproc\fR, + \fBcaddr_t\fR \fIout\fR, \fBcdrproct_t\fR \fIoutproc\fR, + \fBstruct timeval\fR \fItout\fR, \fBrpcport_t *\fR\fIportp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBpmap_set\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, + \fBrpcprot_t\fR \fIprotocol\fR, \fBu_short\fR \fIport\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBpmap_unset\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR); +.fi + +.LP +.nf +int svc_fds; +.fi + +.LP +.nf +\fBstruct sockaddr_in *\fR\fBsvc_getcaller\fR(\fBSVCXPRT *\fR\fIxprt\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_getreq\fR(\fBint\fR \fIrdfds\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvcfd_create\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR, + \fBuint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvcraw_create\fR(void) +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvctcp_create\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR, + \fBuint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvcudp_bufcreate\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR, + \fBuint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvcudp_create\fR(\fBint\fR \fIfd\fR); +.fi + +.LP +.nf +\fB\fR\fBregisterrpc\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, \fBrpcproc_t\fR \fIprocnum\fR, + \fBchar *(*procname)()\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBxdrproc_t\fR \fIoutproc\fR); +.fi + +.LP +.nf +\fBbool_t\fR\fBsvc_register\fR(\fBSVCXPRT *\fR\fIxprt\fR, \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, + \fBvoid (*\fR\fIdispatch()\fR, \fBint\fR \fIprotocol\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_unregister\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_authunix_parms\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct authunix_parms *\fR\fIsupp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBRPC\fR routines allow C programs to make procedure calls on other machines +across the network. First, the client calls a procedure to send a request to +the server. Upon receipt of the request, the server calls a dispatch routine to +perform the requested service, and then sends back a reply. Finally, the +procedure call returns to the client. +.sp +.LP +The routines described in this manual page have been superseded by other +routines. The preferred routine is given after the description of the routine. +New programs should use the preferred routines, as support for the older +interfaces may be dropped in future releases. +.SS "File Descriptors" +.sp +.LP +Transport independent \fBRPC\fR uses \fBTLI\fR as its transport interface +instead of sockets. +.sp +.LP +Some of the routines described in this section (such as \fBclnttcp_create()\fR) +take a pointer to a file descriptor as one of the parameters. If the user wants +the file descriptor to be a socket, then the application will have to be linked +with both \fBlibrpcsoc\fR and \fBlibnsl\fR. If the user passed +\fBRPC_ANYSOCK\fR as the file descriptor, and the application is linked with +\fBlibnsl\fR only, then the routine will return a \fBTLI\fR file descriptor +and not a socket. +.SS "Routines" +.sp +.LP +The following routines require that the header \fB<rpc/rpc.h>\fR be included. +The symbol \fBPORTMAP\fR should be defined so that the appropriate function +declarations for the old interfaces are included through the header files. +.sp +.ne 2 +.mk +.na +\fB\fBauthdes_create()\fR\fR +.ad +.RS 30n +.rt +\fBauthdes_create()\fR is the first of two routines which interface to the +\fBRPC\fR secure authentication system, known as \fBDES\fR authentication. The +second is \fBauthdes_getucred()\fR, below. Note: the keyserver daemon +\fBkeyserv\fR(1M) must be running for the \fBDES\fR authentication system to +work. +.sp +\fBauthdes_create()\fR, used on the client side, returns an authentication +handle that will enable the use of the secure authentication system. The first +parameter \fIname\fR is the network name, or \fInetname\fR, of the owner of the +server process. This field usually represents a hostname derived from the +utility routine \fBhost2netname()\fR, but could also represent a user name +using \fBuser2netname()\fR. See \fBsecure_rpc\fR(3NSL). The second field is +window on the validity of the client credential, given in seconds. A small +window is more secure than a large one, but choosing too small of a window +will increase the frequency of resynchronizations because of clock drift. The +third parameter \fIsyncaddr\fR is optional. If it is \fBNULL,\fR then the +authentication system will assume that the local clock is always in sync with +the server's clock, and will not attempt resynchronizations. If an address is +supplied, however, then the system will use the address for consulting the +remote time service whenever resynchronization is required. This parameter is +usually the address of the \fBRPC\fR server itself. The final parameter +\fIckey\fR is also optional. If it is \fBNULL,\fR then the authentication +system will generate a random \fBDES\fR key to be used for the encryption of +credentials. If it is supplied, however, then it will be used instead. +.sp +This routine exists for backward compatibility only, and it is made obsolete by +\fBauthdes_seccreate()\fR. See \fBsecure_rpc\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthunix_create()\fR\fR +.ad +.RS 30n +.rt +Create and return an \fBRPC\fR authentication handle that contains .UX +authentication information. The parameter \fIhost\fR is the name of the machine +on which the information was created; \fIuid\fR is the user's user \fBID;\fR +\fIgid\fR is the user's current group \fBID;\fR \fIgrouplen\fR and +\fIgidlistp\fR refer to a counted array of groups to which the user belongs. +.sp +It is not very difficult to impersonate a user. +.sp +This routine exists for backward compatibility only, and it is made obsolete by +\fBauthsys_create()\fR. See \fBrpc_clnt_auth\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthunix_create_default()\fR\fR +.ad +.RS 30n +.rt +Call \fBauthunix_create()\fR with the appropriate parameters. +.sp +This routine exists for backward compatibility only, and it is made obsolete by +\fBauthsys_create_default()\fR. See \fBrpc_clnt_auth\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcallrpc()\fR\fR +.ad +.RS 30n +.rt +Call the remote procedure associated with \fIprognum\fR, \fIversnum\fR, and +\fIprocnum\fR on the machine, \fIhost\fR. The parameter \fIinproc\fR is used to +encode the procedure's parameters, and \fIoutproc\fR is used to decode the +procedure's results; \fIin\fR is the address of the procedure's argument, and +\fIout\fR is the address of where to place the result(s). This routine returns +\fB0\fR if it succeeds, or the value of \fBenum clnt_stat\fR cast to an integer +if it fails. The routine \fBclnt_perrno()\fR is handy for translating failure +statuses into messages. See \fBrpc_clnt_calls\fR(3NSL). +.sp +You do not have control of timeouts or authentication using this routine. This +routine exists for backward compatibility only, and is made obsolete by +\fBrpc_call()\fR. See \fBrpc_clnt_calls\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnt_stat_clnt_broadcast()\fR\fR +.ad +.RS 30n +.rt +Like \fBcallrpc()\fR, except the call message is broadcast to all locally +connected broadcast nets. Each time the caller receives a response, this +routine calls \fBeachresult()\fR, whose form is: +.sp +.in +2 +.nf +\fBeachresult(char *\fIout\fR, struct sockaddr_in *\fIaddr\fR);\fR +.fi +.in -2 + +where \fIout\fR is the same as \fIout\fR passed to \fBclnt_broadcast()\fR, +except that the remote procedure's output is decoded there; \fIaddr\fR points +to the address of the machine that sent the results. If \fBeachresult()\fR +returns \fB0\fR. \fBclnt_broadcast()\fR waits for more replies; otherwise it +returns with appropriate status. If \fBeachresult()\fR is \fBNULL,\fR +\fBclnt_broadcast()\fR returns without waiting for any replies. +.sp +Broadcast packets are limited in size to the maximum transfer unit of the +transports involved. For Ethernet, the callers argument size is approximately +1500 bytes. Since the call message is sent to all connected networks, it may +potentially lead to broadcast storms. \fBclnt_broadcast()\fR uses SB AUTH_SYS +credentials by default. See \fBrpc_clnt_auth\fR(3NSL). This routine exists for +backward compatibility only, and is made obsolete by \fBrpc_broadcast()\fR. See +\fBrpc_clnt_calls\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclntraw_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates an internal, memory-based \fBRPC\fR client for the remote +program \fIprognum\fR, version \fIversnum\fR. The transport used to pass +messages to the service is actually a buffer within the process's address +space, so the corresponding \fBRPC\fR server should live in the same address +space. See \fBsvcraw_create()\fR. This allows simulation of \fBRPC\fR and +acquisition of \fBRPC\fR overheads, such as round trip times, without any +kernel interference. This routine returns \fBNULL\fR if it fails. +.sp +This routine exists for backward compatibility only. It has the same +functionality as \fBclnt_raw_create()\fR. See \fBrpc_clnt_create\fR(3NSL), +which obsoletes it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclnttcp_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR, +version \fIversnum\fR; the client uses \fBTCP/IP\fR as a transport. The remote +program is located at Internet address \fIaddr\fR. If +\fIaddr\fR\fB\fR->\fIsin_port\fR is \fB0\fR, then it is set to the actual port +that the remote program is listening on. The remote \fBrpcbind\fR service is +consulted for this information. The parameter \fI*fdp\fR is a file descriptor, +which may be open and bound; if it is \fBRPC_ANYSOCK\fR, then this routine +opens a new one and sets \fI*fdp\fR. Refer to the \fBFile Descriptor\fR section +for more information. Since \fBTCP-based\fR \fBRPC\fR uses buffered \fBI/O,\fR +the user may specify the size of the send and receive buffers with the +parameters \fIsendsz\fR and \fIrecvsz\fR. Values of \fB0\fR choose suitable +defaults. This routine returns \fBNULL\fR if it fails. +.sp +This routine exists for backward compatibility only. \fBclnt_create()\fR, +\fBclnt_tli_create()\fR, or \fBclnt_vc_create()\fR should be used instead. See +\fBrpc_clnt_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclntudp_bufcreate()\fR\fR +.ad +.RS 30n +.rt +Create a client handle for the remote program \fIprognum\fR, on \fIversnum\fR; +the client uses \fBUDP/IP\fR as the transport. The remote program is located +at the Internet address \fIaddr\fR. If \fIaddr\fR->\fIsin_port\fR is \fB0\fR, +it is set to port on which the remote program is listening on (the remote +\fBrpcbind\fR service is consulted for this information). The parameter +\fI*fdp\fR is a file descriptor, which may be open and bound. If it is +\fBRPC_ANYSOCK\fR, then this routine opens a new one and sets \fI*fdp\fR. Refer +to the \fBFile Descriptor\fR section for more information. The \fBUDP\fR +transport resends the call message in intervals of \fBwait\fR time until a +response is received or until the call times out. The total time for the call +to time out is specified by \fBclnt_call()\fR. See \fBrpc_clnt_calls\fR(3NSL). +If successful it returns a client handle, otherwise it returns \fBNULL.\fR The +error can be printed using the \fBclnt_pcreateerror()\fR routine. See +\fBrpc_clnt_create\fR(3NSL). +.sp +The user can specify the maximum packet size for sending and receiving by using +\fIsendsz\fR and \fIrecvsz\fR arguments for \fBUDP-based\fR \fBRPC\fR messages. +.sp +If \fIaddr\fR->\fIsin_port\fR is \fB0\fR and the requested version number +\fIversnum\fR is not registered with the remote portmap service, it returns a +handle if at least a version number for the given program number is registered. +The version mismatch is discovered by a \fBclnt_call()\fR later (see +\fBrpc_clnt_calls\fR(3NSL)). +.sp +This routine exists for backward compatibility only. \fBclnt_tli_create()\fR or +\fBclnt_dg_create()\fR should be used instead. See \fBrpc_clnt_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclntudp_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates an \fBRPC\fR client handle for the remote program +\fIprognum\fR, version \fIversnum\fR; the client uses \fBUDP/IP\fR as a +transport. The remote program is located at Internet address \fIaddr\fR. If +\fIaddr\fR->\fIsin_port\fR is \fB0\fR, then it is set to actual port that the +remote program is listening on. The remote \fBrpcbind\fR service is consulted +for this information. The parameter \fI*fdp\fR is a file descriptor, which may +be open and bound; if it is \fBRPC_ANYSOCK\fR, then this routine opens a new +one and sets \fI*fdp\fR. Refer to the \fBFile Descriptor\fR section for more +information. The \fBUDP\fR transport resends the call message in intervals of +\fBwait\fR time until a response is received or until the call times out. The +total time for the call to time out is specified by \fBclnt_call()\fR. See +\fBrpc_clnt_calls\fR(3NSL). \fBclntudp_create()\fR returns a client handle on +success, otherwise it returns \fBNULL\fR. The error can be printed using the +\fBclnt_pcreateerror()\fR routine. See \fBrpc_clnt_create\fR(3NSL). +.sp +Since \fBUDP-based\fR \fBRPC\fR messages can only hold up to 8 Kbytes of +encoded data, this transport cannot be used for procedures that take large +arguments or return huge results. +.sp +This routine exists for backward compatibility only. \fBclnt_create()\fR, +\fBclnt_tli_create()\fR, or \fBclnt_dg_create()\fR should be used instead. See +\fBrpc_clnt_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBget_myaddress()\fR\fR +.ad +.RS 30n +.rt +Places the local system's \fBIP\fR address into \fI*addr\fR, without consulting +the library routines that deal with \fB/etc/hosts\fR. The port number is always +set to \fBhtons(PMAPPORT)\fR. +.sp +This routine is only intended for use with the \fBRPC\fR library. It returns +the local system's address in a form compatible with the \fBRPC\fR library, +and should not be taken as the system's actual IP address. In fact, the +\fI*addr\fR buffer's host address part is actually zeroed. This address may +have only local significance and should not be assumed to be an address that +can be used to connect to the local system by remote systems or processes. +.sp +This routine remains for backward compatibility only. The routine +\fBnetdir_getbyname()\fR should be used with the name \fBHOST_SELF\fR to +retrieve the local system's network address as a \fInetbuf\fR structure. See +\fBnetdir\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgetrpcport()\fR\fR +.ad +.RS 30n +.rt +\fBgetrpcport()\fR returns the port number for the version \fIversnum\fR of the +\fBRPC\fR program \fIprognum\fR running on \fIhost\fR and using protocol +\fIproto\fR. \fBgetrpcport()\fR returns \fB0\fR if the \fBRPC\fR system +failed to contact the remote portmap service, the program associated with +\fIprognum\fR is not registered, or there is no mapping between the program and +a port. +.sp +This routine exists for backward compatibility only. Enhanced functionality is +provided by \fBrpcb_getaddr()\fR. See \fBrpcbind\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmaplist()\fR\fR +.ad +.RS 30n +.rt +A user interface to the \fBportmap\fR service, which returns a list of the +current \fBRPC\fR program-to-port mappings on the host located at \fBIP\fR +address \fIaddr\fR. This routine can return \fBNULL .\fR The command +`\fBrpcinfo\fR\fB-p\fR' uses this routine. +.sp +This routine exists for backward compatibility only, enhanced functionality is +provided by \fBrpcb_getmaps()\fR. See \fBrpcbind\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_getport()\fR\fR +.ad +.RS 30n +.rt +A user interface to the \fBportmap\fR service, which returns the port number +on which waits a service that supports program \fIprognum\fR, version +\fIversnum\fR, and speaks the transport protocol associated with +\fIprotocol\fR. The value of \fIprotocol\fR is most likely \fBIPPROTO_UDP\fR or +\fBIPPROTO_TCP\fR. A return value of \fB0\fR means that the mapping does not +exist or that the \fBRPC\fR system failured to contact the remote \fBportmap\fR +service. In the latter case, the global variable \fBrpc_createerr\fR contains +the \fB RPC\fR status. +.sp +This routine exists for backward compatibility only, enhanced functionality is +provided by \fBrpcb_getaddr()\fR. See \fBrpcbind\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_rmtcall()\fR\fR +.ad +.RS 30n +.rt +Request that the \fBportmap\fR on the host at \fBIP\fR address \fI*addr\fR make +an \fBRPC\fR on the behalf of the caller to a procedure on that host. +\fI*portp\fR is modified to the program's port number if the procedure +succeeds. The definitions of other parameters are discussed in \fBcallrpc()\fR +and \fBclnt_call()\fR. See \fBrpc_clnt_calls\fR(3NSL). +.sp +This procedure is only available for the UDP transport. +.sp +If the requested remote procedure is not registered with the remote +\fBportmap\fR then no error response is returned and the call times out. Also, +no authentication is done. +.sp +This routine exists for backward compatibility only, enhanced functionality is +provided by \fBrpcb_rmtcall()\fR. See \fBrpcbind\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_set()\fR\fR +.ad +.RS 30n +.rt +A user interface to the \fBportmap\fR service, that establishes a mapping +between the triple [\fIprognum\fR, \fIversnum\fR, \fIprotocol\fR] and +\fIport\fR on the machine's \fBportmap\fR service. The value of \fIprotocol\fR +may be \fBIPPROTO_UDP\fR or \fBIPPROTO_TCP\fR. Formerly, the routine failed if +the requested \fIport\fR was found to be in use. Now, the routine only fails +if it finds that \fIport\fR is still bound. If \fIport\fR is not bound, the +routine completes the requested registration. This routine returns \fB1\fR if +it succeeds, \fB0\fR otherwise. Automatically done by \fBsvc_register()\fR. +.sp +This routine exists for backward compatibility only, enhanced functionality is +provided by \fBrpcb_set()\fR. See \fBrpcbind\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpmap_unset()\fR\fR +.ad +.RS 30n +.rt +A user interface to the \fBportmap\fR service, which destroys all mapping +between the triple [\fIprognum\fR, \fIversnum\fR, \fIall-protocols\fR] and +\fIport\fR on the machine's \fBportmap\fR service. This routine returns one if +it succeeds, \fB0\fR otherwise. +.sp +This routine exists for backward compatibility only, enhanced functionality is +provided by \fBrpcb_unset()\fR. See \fBrpcbind\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_fds()\fR\fR +.ad +.RS 30n +.rt +A global variable reflecting the \fBRPC\fR service side's read file descriptor +bit mask; it is suitable as a parameter to the \fBselect()\fR call. This is +only of interest if a service implementor does not call \fBsvc_run()\fR, but +rather does his own asynchronous event processing. This variable is read-only , +yet it may change after calls to \fBsvc_getreq()\fR or any creation routines. +Do not pass its address to \fBselect()\fR! Similar to \fBsvc_fdset\fR, but +limited to 32 descriptors. +.sp +This interface is made obsolete by \fBsvc_fdset\fR. See +\fBrpc_svc_calls\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getcaller()\fR\fR +.ad +.RS 30n +.rt +This routine returns the network address, represented as a \fBstruct +sockaddr_in\fR, of the caller of a procedure associated with the \fBRPC\fR +service transport handle, \fIxprt\fR. +.sp +This routine exists for backward compatibility only, and is obsolete. The +preferred interface is \fBsvc_getrpccaller()\fR. See \fBrpc_svc_reg\fR(3NSL), +which returns the address as a \fBstruct netbuf\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_getreq()\fR\fR +.ad +.RS 30n +.rt +This routine is only of interest if a service implementor does not call +\fBsvc_run()\fR, but instead implements custom asynchronous event processing. +It is called when the \fBselect()\fR call has determined that an \fBRPC\fR +request has arrived on some \fBRPC\fR file descriptors; \fIrdfds\fR is the +resultant read file descriptor bit mask. The routine returns when all file +descriptors associated with the value of \fIrdfds\fR have been serviced. This +routine is similar to \fBsvc_getreqset()\fR but is limited to 32 descriptors. +.sp +This interface is made obsolete by \fBsvc_getreqset()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fBsvcfd_create\fB()\fR\fR +.ad +.RS 30n +.rt +Create a service on top of any open and bound descriptor. Typically, this +descriptor is a connected file descriptor for a stream protocol. Refer to the +\fBFile Descriptor\fR section for more information. \fIsendsz\fR and +\fIrecvsz\fR indicate sizes for the send and receive buffers. If they are +\fB0\fR, a reasonable default is chosen. +.sp +This interface is made obsolete by \fBsvc_fd_create()\fR (see +\fBrpc_svc_create\fR(3NSL)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcraw_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates an internal, memory-based \fBRPC\fR service transport, to +which it returns a pointer. The transport is really a buffer within the +process's address space, so the corresponding \fBRPC\fR client should live in +the same address space; see \fBclntraw_create()\fR. This routine allows +simulation of \fBRPC\fR and acquisition of \fBRPC\fR overheads (such as round +trip times), without any kernel interference. This routine returns \fBNULL\fR +if it fails. +.sp +This routine exists for backward compatibility only, and has the same +functionality of \fBsvc_raw_create()\fR. See \fBrpc_svc_create\fR(3NSL), which +obsoletes it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvctcp_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates a \fBTCP/IP-based\fR \fBRPC\fR service transport, to which +it returns a pointer. The transport is associated with the file descriptor +\fIfd\fR, which may be \fBRPC_ANYSOCK\fR, in which case a new file descriptor +is created. If the file descriptor is not bound to a local \fBTCP\fR port, then +this routine binds it to an arbitrary port. Refer to the \fBFile Descriptor\fR +section for more information. Upon completion, \fIxprt\fR->\fBxp_fd\fR is the +transport's file descriptor, and \fIxprt\fR->\fBxp_port\fR is the transport's +port number. This routine returns \fBNULL\fR if it fails. Since \fBTCP-based\fR +\fBRPC\fR uses buffered \fBI/O,\fR users may specify the size of buffers; +values of \fB0\fR choose suitable defaults. +.sp +This routine exists for backward compatibility only. \fBsvc_create()\fR, +\fBsvc_tli_create()\fR, or \fBsvc_vc_create()\fR should be used instead. See +\fBrpc_svc_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcudp_bufcreate()\fR\fR +.ad +.RS 30n +.rt +This routine creates a \fBUDP/IP-based\fR \fBRPC\fR service transport, to which +it returns a pointer. The transport is associated with the file descriptor +\fIfd\fR. If \fIfd\fR is \fBRPC_ANYSOCK\fR then a new file descriptor is +created. If the file descriptor is not bound to a local \fBUDP\fR port, then +this routine binds it to an arbitrary port. Upon completion, +\fIxprt\fR\fBxp_fd\fR is the transport's file descriptor, and +\fIxprt\fR->\fBxp_port\fR is the transport's port number. Refer to the \fBFile +Descriptor\fR section for more information. This routine returns \fBNULL\fR if +it fails. +.sp +The user specifies the maximum packet size for sending and receiving UDP-based +\fBRPC\fR messages by using the \fIsendsz\fR and \fIrecvsz\fR parameters. +.sp +This routine exists for backward compatibility only. \fBsvc_tli_create()\fR, or +\fBsvc_dg_create()\fR should be used instead. See \fBrpc_svc_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvcudp_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates a \fBUDP/IP-based\fR \fBRPC\fR service transport, to which +it returns a pointer. The transport is associated with the file descriptor +\fIfd\fR, which may be \fBRPC_ANYSOCK\fR, in which case a new file descriptor +is created. If the file descriptor is not bound to a local \fBUDP\fR port, then +this routine binds it to an arbitrary port. Upon completion, +\fIxprt\fR->\fBxp_fd\fR is the transport's file descriptor, and +\fIxprt\fR->\fBxp_port\fR is the transport's port number. This routine returns +\fBNULL\fR if it fails. +.sp +Since \fBUDP-based\fR \fBRPC\fR messages can only hold up to 8 Kbytes of +encoded data, this transport cannot be used for procedures that take large +arguments or return huge results. +.sp +This routine exists for backward compatibility only. \fBsvc_create()\fR, +\fBsvc_tli_create()\fR, or \fBsvc_dg_create()\fR should be used instead. See +\fBrpc_svc_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBregisterrpc()\fR\fR +.ad +.RS 30n +.rt +Register program \fIprognum\fR, procedure \fIprocname\fR, and version +\fIversnum\fR with the \fBRPC\fR service package. If a request arrives for +program \fIprognum\fR, version \fIversnum\fR, and procedure \fIprocnum\fR, +\fIprocname\fR is called with a pointer to its parameter(s). \fIprocname\fR +should return a pointer to its static result(s). \fIinproc\fR is used to decode +the parameters while \fIoutproc\fR is used to encode the results. This routine +returns \fB0\fR if the registration succeeded, \(mi1 otherwise. +.sp +\fBsvc_run()\fR must be called after all the services are registered. +.sp +This routine exists for backward compatibility only, and it is made obsolete by +\fBrpc_reg()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_register()\fR\fR +.ad +.RS 30n +.rt +Associates \fIprognum\fR and \fIversnum\fR with the service dispatch procedure, +\fIdispatch\fR. If \fIprotocol\fR is \fB0\fR, the service is not registered +with the \fBportmap\fR service. If \fIprotocol\fR is non-zero, then a mapping +of the triple [\fIprognum\fR, \fIversnum\fR, \fIprotocol\fR] to +\fIxprt\fR->\fBxp_port\fR is established with the local \fBportmap\fR service +(generally \fIprotocol\fR is \fB0\fR, \fBIPPROTO_UDP\fR or \fBIPPROTO_TCP\fR). +The procedure \fIdispatch\fR has the following form: +.sp +.in +2 +.nf +\fBdispatch(struct svc_req *\fIrequest\fR, SVCXPRT *\fIxprt\fR);\fR +.fi +.in -2 + +The \fBsvc_register()\fR routine returns one if it succeeds, and \fB0\fR +otherwise. +.sp +This routine exists for backward compatibility only. Enhanced functionality is +provided by \fBsvc_reg()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_unregister()\fR\fR +.ad +.RS 30n +.rt +Remove all mapping of the double [\fIprognum\fR, \fIversnum\fR] to dispatch +routines, and of the triple [\fIprognum\fR, \fIversnum\fR, \fIall-protocols\fR] +to port number from \fBportmap\fR. +.sp +This routine exists for backward compatibility. Enhanced functionality is +provided by \fBsvc_unreg()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_authunix_parms()\fR\fR +.ad +.RS 30n +.rt +Used for describing \fBUNIX\fR credentials. This routine is useful for users +who wish to generate these credentials without using the \fBRPC\fR +authentication package. +.sp +This routine exists for backward compatibility only, and is made obsolete by +\fBxdr_authsys_parms()\fR. See \fBrpc_xdr\fR(3NSL). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkeyserv\fR(1M), \fBrpcbind\fR(1M), \fBrpcinfo\fR(1M), \fBnetdir\fR(3NSL), +\fBnetdir_getbyname\fR(3NSL), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), +\fBrpc_clnt_calls\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), +\fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), +\fBrpc_svc_reg\fR(3NSL), \fBrpc_xdr\fR(3NSL), \fBrpcbind\fR(3NSL), +\fBsecure_rpc\fR(3NSL), \fBselect\fR(3C), \fBxdr_authsys_parms\fR(3NSL), +\fBlibnsl\fR(3LIB), \fBlibrpcsoc\fR(3LIBUCB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +These interfaces are unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/rpc_svc_calls.3nsl b/usr/src/man/man3nsl/rpc_svc_calls.3nsl new file mode 100644 index 0000000000..48db208bbe --- /dev/null +++ b/usr/src/man/man3nsl/rpc_svc_calls.3nsl @@ -0,0 +1,284 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2004 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_svc_calls 3NSL "26 Jan 2004" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_svc_calls, svc_dg_enablecache, svc_done, svc_exit, svc_fdset, svc_freeargs, +svc_getargs, svc_getreq_common, svc_getreq_poll, svc_getreqset, +svc_getrpccaller, svc_max_pollfd, svc_pollfd, svc_run, svc_sendreply, +svc_getcallerucred, svc_fd_negotiate_ucred \- library routines for RPC servers +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...] +#include <rpc/rpc.h> + +\fBint\fR \fBsvc_dg_enablecache\fR(\fBSVCXPRT *\fR\fIxprt\fR, \fBconst uint_t\fR \fIcache_size\fR); +.fi + +.LP +.nf +\fBint\fR \fBsvc_done\fR(\fBSVCXPRT *\fR\fIxprt\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_exit\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_fd_negotiate_ucred\fR(\fBint\fR \fIfd\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBsvc_freeargs\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBconst txdrproc_t\fR \fIinproc\fR, + \fBcaddr_t\fR \fIin\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBsvc_getargs\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBconst xdrproc_t\fR \fIinproc\fR, + \fBcaddr_t\fR \fIin\fR); +.fi + +.LP +.nf +\fBint\fR \fBsvc_getcallerucred\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBucred_t **\fR\fIucred\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_getreq_common\fR(\fBconst int\fR \fIfd\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_getreqset\fR(\fBfd_set *\fR\fIrdfds\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_getreq_poll\fR(\fBstruct pollfd *\fR\fIpfdp\fR, \fBconst int\fR \fIpollretval\fR); +.fi + +.LP +.nf +\fBstruct netbuf *\fR\fBsvc_getrpccaller\fR(\fBconst SVCXPRT *\fR\fIxprt\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_run\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBsvc_sendreply\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBconst xdrproc_t\fR \fIoutproc\fR, + \fBcaddr_t\fR \fIout\fRint svc_max_pollfd; +fd_set svc_fdset; +pollfd_t *svc_pollfd; +.fi + +.SH DESCRIPTION +.sp +.LP +These routines are part of the \fBRPC\fR library which allows C language +programs to make procedure calls on other machines across the network. +.sp +.LP +These routines are associated with the server side of the \fBRPC\fR mechanism. +Some of them are called by the server side dispatch function. Others, such as +\fBsvc_run()\fR, are called when the server is initiated. +.sp +.LP +Because the service transport handle \fBSVCXPRT\fR contains a single data area +for decoding arguments and encoding results, the structure cannot freely be +shared between threads that call functions to decode arguments and encode +results. When a server is operating in the Automatic or User MT modes, however, +a copy of this structure is passed to the service dispatch procedure in order +to enable concurrent request processing. Under these circumstances, some +routines which would otherwise be Unsafe, become Safe. These are marked as +such. Also marked are routines that are Unsafe for multithreaded applications, +and are not to be used by such applications. See \fBrpc\fR(3NSL) for the +definition of the \fBSVCXPRT\fR data structure. +.sp +.LP +The \fBsvc_dg_enablecache()\fR function allocates a duplicate request cache for +the service endpoint \fIxprt\fR, large enough to hold \fIcache_size\fR entries. +Once enabled, there is no way to disable caching. The function returns \fB1\fR +if space necessary for a cache of the given size was successfully allocated, +and \fB0\fR otherwise. This function is Safe in multithreaded applications. +.sp +.LP +The \fBsvc_done()\fR function frees resources allocated to service a client +request directed to the service endpoint \fIxprt\fR. This call pertains only to +servers executing in the User MT mode. In the User MT mode, service procedures +must invoke this call before returning, either after a client request has been +serviced, or after an error or abnormal condition that prevents a reply from +being sent. After \fBsvc_done\fR() is invoked, the service endpoint \fIxprt\fR +should not be referenced by the service procedure. Server multithreading modes +and parameters can be set using the \fBrpc_control\fR() call. This function is +Safe in multithreaded applications. It will have no effect if invoked in modes +other than the User MT mode. +.sp +.LP +The \fBsvc_exit()\fR function when called by any of the RPC server procedures +or otherwise, destroys all services registered by the server and causes +\fBsvc_run()\fR to return. If RPC server activity is to be resumed, services +must be reregistered with the RPC library either through one of the +\fBrpc_svc_create\fR(3NSL) functions, or using \fBxprt_register\fR(3NSL). The +\fBsvc_exit()\fR function has global scope and ends all RPC server activity. +.sp +.LP +The \fBsvc_freeargs()\fR function macro frees any data allocated by the +\fBRPC/XDR\fR system when it decoded the arguments to a service procedure using +\fBsvc_getargs()\fR. This routine returns \fBTRUE\fR if the results were +successfully freed, and \fBFALSE\fR otherwise. This function macro is Safe in +multithreaded applications utilizing the Automatic or User MT modes. +.sp +.LP +The \fBsvc_getargs()\fR function macro decodes the arguments of an \fBRPC\fR +request associated with the \fBRPC\fR service transport handle \fIxprt\fR. The +parameter \fIin\fR is the address where the arguments will be placed; +\fIinproc\fR is the \fBXDR\fR routine used to decode the arguments. This +routine returns \fBTRUE\fR if decoding succeeds, and \fBFALSE\fR otherwise. +This function macro is Safe in multithreaded applications utilizing the +Automatic or User MT modes. +.sp +.LP +The \fBsvc_getreq_common()\fR function is called to handle a request on a file +descriptor. +.sp +.LP +The \fBsvc_getreq_poll()\fR function is only of interest if a service +implementor does not call \fBsvc_run()\fR, but instead implements custom +asynchronous event processing. It is called when \fBpoll\fR(2) has determined +that an RPC request has arrived on some RPC file descriptors; \fIpollretval\fR +is the return value from \fBpoll\fR(2) and \fIpfdp\fR is the array of +\fIpollfd\fR structures on which the \fBpoll\fR(2) was done. It is assumed to +be an array large enough to contain the maximal number of descriptors allowed. +The \fBsvc_getreq_poll()\fR function macro is Unsafe in multithreaded +applications. +.sp +.LP +The \fBsvc_getreqset()\fR function is only of interest if a service implementor +does not call \fBsvc_run()\fR, but instead implements custom asynchronous event +processing. It is called when \fBselect\fR(3C) has determined that an \fBRPC\fR +request has arrived on some \fBRPC\fR file descriptors; \fIrdfds\fR is the +resultant read file descriptor bit mask. The routine returns when all file +descriptors associated with the value of \fIrdfds\fR have been serviced. This +function macro is Unsafe in multithreaded applications. +.sp +.LP +The \fBsvc_getrpccaller()\fR function is the approved way of getting the +network address of the caller of a procedure associated with the \fBRPC\fR +service transport handle \fIxprt\fR. This function macro is Safe in +multithreaded applications. +.sp +.LP +The \fBsvc_run()\fR function never returns. In single-threaded mode, the +function waits for \fBRPC\fR requests to arrive. When an RPC request arrives, +the \fBsvc_run()\fR function calls the appropriate service procedure. This +procedure is usually waiting for the \fBpoll\fR(2) library call to return. +.sp +.LP +Applications that execute in the Automatic or the User MT mode should invoke +the \fBsvc_run()\fR function exactly once. In the Automatic MT mode, the +\fBsvc_run()\fR function creates threads to service client requests. In the +User MT mode, the function provides a framework for service developers to +create and manage their own threads for servicing client requests. +.sp +.LP +The \fBsvc_fdset\fR global variable reflects the \fBRPC\fR server's read file +descriptor bit mask. This is only of interest if service implementors do not +call \fBsvc_run()\fR, but rather do their own asynchronous event processing. +This variable is read-only may change after calls to \fBsvc_getreqset()\fR or +after any creation routine. Do not pass its address to \fBselect\fR(3C). +Instead, pass the address of a copy. multithreaded applications executing in +either the Automatic MT mode or the user MT mode should never read this +variable. They should use auxiliary threads to do asynchronous event +processing. The \fBsvc_fdset\fR variable is limited to 1024 file descriptors +and is considered obsolete. Use of \fBsvc_pollfd\fR is recommended instead. +.sp +.LP +The \fBsvc_pollfd\fR global variable points to an array of \fBpollfd_t\fR +structures that reflect the \fBRPC\fR server's read file descriptor array. This +is only of interest if service service implementors do not call \fBsvc_run()\fR +but rather do their own asynchronous event processing. This variable is +read-only, and it may change after calls to \fBsvc_getreg_poll()\fR or any +creation routines. Do no pass its address to \fBpoll\fR(2). Instead, pass the +address of a copy. By default, \fBsvc_pollfd\fR is limited to 1024 entries. Use +\fBrpc_control\fR(3NSL) to remove this limitation. multithreaded applications +executing in either the Automatic MT mode or the user MT mode should never be +read this variable. They should use auxiliary threads to do asynchronous event +processing. +.sp +.LP +The \fBsvc_max_pollfd\fR global variable contains the maximum length of the +\fBsvc_pollfd\fR array. This variable is read-only, and it may change after +calls to \fBsvc_getreg_poll()\fR or any creation routines. +.sp +.LP +The \fBsvc_sendreply()\fR function is called by an \fBRPC\fR service dispatch +routine to send the results of a remote procedure call. The \fIxprt\fR +parameter is the transport handle of the request. The \fIoutproc\fR parameter +is the \fBXDR\fR routine used to encode the results. The \fIout\fR parameter is +the address of the results. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. The \fBsvc_sendreply()\fR function macro is Safe in +multithreaded applications that use the Automatic or the User MT mode. +.sp +.LP +The \fBsvc_fd_negotiate_ucred()\fR function is called by an RPC server to +inform the underlying transport that the function wishes to receive +\fBucreds\fR for local calls, including those over IP transports. +.sp +.LP +The \fBsvc_getcallerucred()\fR function attempts to retrieve the \fBucred_t\fR +associated with the caller. The function returns \fB\fR0 when successful and +\fB-1\fR when not. +.sp +.LP +When successful, the \fBsvc_getcallerucred()\fR function stores the pointer to +a freshly allocated \fBucred_t\fR in the memory location pointed to by the +\fIucred\fR argument if that memory location contains the null pointer. If the +memory location is non-null, the function reuses the existing \fBucred_t\fR. +When \fIucred\fR is no longer needed, a credential allocated by +\fBsvc_getcallerucred()\fR should be freed with \fBucred_free\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of attribute types and values. +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSee below. +.TE + +.sp +.LP +The \fBsvc_fd_negotiate_ucred()\fR, \fBsvc_dg_enablecache()\fR, +\fBsvc_getrpccaller()\fR, and \fBsvc_getcallerucred()\fR functions are Safe in +multithreaded applications. The \fBsvc_freeargs()\fR, \fBsvc_getargs()\fR, and +\fBsvc_sendreply()\fR functions are Safe in multithreaded applications that use +the Automatic or the User MT mode. The \fBsvc_getreq_common()\fR, +\fBsvc_getreqset()\fR, and \fBsvc_getreq_poll()\fR functions are Unsafe in +multithreaded applications and should be called only from the main thread. +.SH SEE ALSO +.sp +.LP +\fBrpcgen\fR(1), \fBpoll\fR(2), \fBgetpeerucred\fR(3C), \fBrpc\fR(3NSL), +\fBrpc_control\fR(3NSL), \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), +\fBrpc_svc_reg\fR(3NSL), \fBselect\fR(3C), \fBucred_free\fR(3C), +\fBxprt_register\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_svc_create.3nsl b/usr/src/man/man3nsl/rpc_svc_create.3nsl new file mode 100644 index 0000000000..e65774d687 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_svc_create.3nsl @@ -0,0 +1,426 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_svc_create 3NSL "22 Mar 2005" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create, +svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create, svc_vc_create, +svc_door_create \- server handle creation routines +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpc.h> + +\fBbool_t\fR \fBsvc_control\fR(\fBSVCXPRT *\fR\fIsvc\fR, \fBconst uint_t\fR \fIreq\fR, \fBvoid *\fR\fIinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBsvc_create\fR(\fBconst void (*\fR\fIdispatch\fR)const struct svc_req *, + const SVCXPRT *, \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst char *\fR\fInettype\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsvc_destroy\fR(\fBSVCXPRT *\fR\fIxprt\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_dg_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR, + \fBconst uint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_fd_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR, + \fBconst uint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_raw_create\fR(void) +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_tli_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst struct netconfig *\fR\fInetconf\fR, + \fBconst struct t_bind *\fR\fIbind_addr\fR, \fBconst uint_t\fR \fIsendsz\fR, + \fBconst uint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_tp_create\fR(\fBconst void (*\fR\fIdispatch\fR) + const struct svc_req *, const SVCXPRT *), \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst struct netconfig *\fR\fInetconf\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_vc_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR, + \fBconst uint_t\fR \fIrecvsz\fR); +.fi + +.LP +.nf +\fBSVCXPRT *\fR\fBsvc_door_create\fR(\fBvoid (*\fR\fIdispatch\fR)(struct svc_req *, SVCXPRT *), + \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst uint_t\fR \fIsendsz\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These routines are part of the \fBRPC\fR library which allows C language +programs to make procedure calls on servers across the network. These routines +deal with the creation of service handles. Once the handle is created, the +server can be invoked by calling \fBsvc_run()\fR. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure. +.sp +.ne 2 +.mk +.na +\fB\fBsvc_control()\fR\fR +.ad +.RS 21n +.rt +A function to change or retrieve information about a service object. \fIreq\fR +indicates the type of operation and \fIinfo\fR is a pointer to the information. +The supported values of \fIreq\fR, their argument types, and what they do are: +.sp +.ne 2 +.mk +.na +\fB\fBSVCGET_VERSQUIET\fR\fR +.ad +.RS 25n +.rt +If a request is received for a program number served by this server but the +version number is outside the range registered with the server, an +\fBRPC_PROGVERSMISMATCH\fR error will normally be returned. \fIinfo\fR should +be a pointer to an integer. Upon successful completion of the +\fBSVCGET_VERSQUIET\fR request, *\fIinfo\fR contains an integer which +describes the server's current behavior: \fB0\fR indicates normal server +behavior, that is, an \fBRPC_PROGVERSMISMATCH\fR error will be returned. +\fB1\fR indicates that the out of range request will be silently ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSVCSET_VERSQUIET\fR\fR +.ad +.RS 25n +.rt +If a request is received for a program number served by this server but the +version number is outside the range registered with the server, an +\fBRPC_PROGVERSMISMATCH\fR error will normally be returned. It is sometimes +desirable to change this behavior. \fIinfo\fR should be a pointer to an integer +which is either \fB0\fR, indicating normal server behavior and an +\fBRPC_PROGVERSMISMATCH\fR error will be returned, or \fB1\fR, indicating that +the out of range request should be silently ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSVCGET_XID\fR\fR +.ad +.RS 25n +.rt +Returns the transaction \fBID\fR of connection\(mioriented and connectionless +transport service calls. The transaction \fBID\fR assists in uniquely +identifying client requests for a given \fBRPC\fR version, program number, +procedure, and client. The transaction \fBID\fR is extracted from the service +transport handle \fIsvc\fR. \fIinfo\fR must be a pointer to an unsigned long. +Upon successful completion of the \fBSVCGET_XID\fR request, *\fIinfo\fR +contains the transaction \fBID\fR. Note that rendezvous and raw service +handles do not define a transaction \fBID\fR. Thus, if the service handle is +of rendezvous or raw type, and the request is of type \fBSVCGET_XID,\fR +\fBsvc_control()\fR will return \fBFALSE\fR. Note also that the transaction +\fBID\fR read by the server can be set by the client through the suboption +\fBCLSET_XID\fR in \fBclnt_control()\fR. See \fBclnt_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSVCSET_RECVERRHANDLER\fR\fR +.ad +.RS 25n +.rt +Attaches or detaches a disconnection handler to the service handle, \fIsvc\fR, +that will be called when a transport error arrives during the reception of a +request or when the server is waiting for a request and the connection shuts +down. This handler is only useful for a connection oriented service handle. +.sp +\fI*info\fR contains the address of the error handler to attach, or \fINULL\fR +to detach a previously defined one. The error handler has two arguments. It has +a pointer to the erroneous service handle. It also has an integer that +indicates if the full service is closed (when equal to zero), or that only one +connection on this service is closed (when not equal to zero). +.sp +.in +2 +.nf +void handler (const SVCXPRT *svc, const bool_t isAConnection); +.fi +.in -2 + +With the service handle address, \fIsvc\fR, the error handler is able to detect +which connection has failed and to begin an error recovery process. The error +handler can be called by multiple threads and should be implemented in an +MT-safe way. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSVCGET_RECVERRHANDLER\fR\fR +.ad +.RS 25n +.rt +Upon successful completion of the \fBSVCGET_RECVERRHANDLER\fR request, +\fI*info\fR contains the address of the handler for receiving errors. Upon +failure, \fI*info\fR contains \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSVCSET_CONNMAXREC\fR\fR +.ad +.RS 25n +.rt +Set the maximum record size (in bytes) and enable non-blocking mode for this +service handle. Value can be set and read for both connection and +non-connection oriented transports, but is silently ignored for the +non-connection oriented case. The \fIinfo\fR argument should be a pointer to an +\fBint\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSVCGET_CONNMAXREC\fR\fR +.ad +.RS 25n +.rt +Get the maximum record size for this service handle. Zero means no maximum in +effect and the connection is in blocking mode. The result is not significant +for non-connection oriented transports. The \fIinfo\fR argument should be a +pointer to an \fBint\fR. +.RE + +This routine returns TRUE if the operation was successful. Otherwise, it +returns false. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_create()\fR\fR +.ad +.RS 21n +.rt +\fBsvc_create()\fR creates server handles for all the transports belonging to +the class \fInettype\fR. +.sp +\fInettype\fR defines a class of transports which can be used for a particular +application. The transports are tried in left to right order in \fBNETPATH\fR +variable or in top to bottom order in the netconfig database. If \fInettype\fR +is \fINULL,\fR it defaults to \fBnetpath\fR. +.sp +\fBsvc_create()\fR registers itself with the \fBrpcbind\fR service (see +\fBrpcbind\fR(1M)). \fIdispatch\fR is called when there is a remote procedure +call for the given \fIprognum\fR and \fIversnum\fR; this requires calling +\fBsvc_run()\fR (see \fBsvc_run()\fR in \fBrpc_svc_reg\fR(3NSL)). If +\fBsvc_create()\fR succeeds, it returns the number of server handles it +created, otherwise it returns \fB0\fR and an error message is logged. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_destroy()\fR\fR +.ad +.RS 21n +.rt +A function macro that destroys the \fBRPC\fR service handle \fIxprt\fR. +Destruction usually involves deallocation of private data structures, including +\fIxprt\fR itself. Use of \fIxprt\fR is undefined after calling this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_dg_create()\fR\fR +.ad +.RS 21n +.rt +This routine creates a connectionless \fBRPC\fR service handle, and returns a +pointer to it. This routine returns \fINULL\fR if it fails, and an error +message is logged. \fIsendsz\fR and \fIrecvsz\fR are parameters used to specify +the size of the buffers. If they are \fB0\fR, suitable defaults are chosen. The +file descriptor \fIfildes\fR should be open and bound. The server is not +registered with \fBrpcbind\fR(1M). +.sp +Warning: since connectionless-based \fBRPC\fR messages can only hold limited +amount of encoded data, this transport cannot be used for procedures that take +large arguments or return huge results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_fd_create()\fR\fR +.ad +.RS 21n +.rt +This routine creates a service on top of an open and bound file descriptor, and +returns the handle to it. Typically, this descriptor is a connected file +descriptor for a connection-oriented transport. \fIsendsz\fR and \fIrecvsz\fR +indicate sizes for the send and receive buffers. If they are \fB0\fR, +reasonable defaults are chosen. This routine returns \fINULL\fR if it fails, +and an error message is logged. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_raw_create()\fR\fR +.ad +.RS 21n +.rt +This routine creates an \fBRPC\fR service handle and returns a pointer to it. +The transport is really a buffer within the process's address space, so the +corresponding \fBRPC\fR client should live in the same address space; (see +\fBclnt_raw_create()\fR in \fBrpc_clnt_create\fR(3NSL)). This routine allows +simulation of \fBRPC\fR and acquisition of \fBRPC\fR overheads (such as round +trip times), without any kernel and networking interference. This routine +returns \fINULL\fR if it fails, and an error message is logged. +.sp +Note: \fBsvc_run()\fR should not be called when the raw interface is being +used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_tli_create()\fR\fR +.ad +.RS 21n +.rt +This routine creates an \fBRPC\fR server handle, and returns a pointer to it. +\fIfildes\fR is the file descriptor on which the service is listening. If +\fIfildes\fR is \fBRPC_ANYFD\fR, it opens a file descriptor on the transport +specified by \fInetconf\fR. If the file descriptor is unbound and +\fIbindaddr\fR is non-null \fIfildes\fR is bound to the address specified by +\fIbindaddr\fR, otherwise \fIfildes\fR is bound to a default address chosen by +the transport. In the case where the default address is chosen, the number of +outstanding connect requests is set to 8 for connection-oriented transports. +The user may specify the size of the send and receive buffers with the +parameters \fIsendsz\fR and \fIrecvsz\fR \fI;\fR values of \fB0\fR choose +suitable defaults. This routine returns \fINULL\fR if it fails, and an error +message is logged. The server is not registered with the \fBrpcbind\fR(1M) +service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_tp_create()\fR\fR +.ad +.RS 21n +.rt +\fBsvc_tp_create()\fR creates a server handle for the network specified by +\fInetconf\fR, and registers itself with the \fBrpcbind\fR service. +\fIdispatch\fR is called when there is a remote procedure call for the given +\fIprognum\fR and \fIversnum\fR; this requires calling \fBsvc_run()\fR. +\fBsvc_tp_create()\fR returns the service handle if it succeeds, otherwise a +\fINULL\fR is returned and an error message is logged. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_vc_create()\fR\fR +.ad +.RS 21n +.rt +This routine creates a connection-oriented \fBRPC\fR service and returns a +pointer to it. This routine returns \fINULL\fR if it fails, and an error +message is logged. The users may specify the size of the send and receive +buffers with the parameters \fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR +choose suitable defaults. The file descriptor \fIfildes\fR should be open and +bound. The server is not registered with the \fBrpcbind\fR(1M) service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_door_create()\fR\fR +.ad +.RS 21n +.rt +This routine creates an RPC server handle over doors and returns a pointer to +it. Doors is a transport mechanism that facilitates fast data transfer between +processes on the same machine. for the given program The user may set the size +of the send buffer with the parameter \fIsendsz\fR. If \fIsendsz\fR is 0, the +corresponding default buffer size is 16 Kbyte. If successful, the +\fBsvc_door_create()\fR routine returns the service handle. Otherwise it +returns \fINULL\fR and sets a value for \fBrpc_createerr\fR. The server is not +registered with \fBrpcbind\fR(1M). The \fBSVCSET_CONNMAXREC\fR and +\fBSVCGET_CONNMAXREC\fR \fBsvc_control()\fR requests can be used to set and +change the maximum allowed request size for the doors transport. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitectureAll +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), +\fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpc_svc_reg\fR(3NSL), +\fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_svc_err.3nsl b/usr/src/man/man3nsl/rpc_svc_err.3nsl new file mode 100644 index 0000000000..7f731dd1ce --- /dev/null +++ b/usr/src/man/man3nsl/rpc_svc_err.3nsl @@ -0,0 +1,143 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_svc_err 3NSL "20 Feb 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_svc_err, svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, +svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for +server side remote procedure call errors +.SH DESCRIPTION +.sp +.LP +These routines are part of the \fBRPC\fR library which allows C language +programs to make procedure calls on other machines across the network. +.sp +.LP +These routines can be called by the server side dispatch function if there is +any error in the transaction with the client. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure. +.sp +.in +2 +.nf +\fB#include <rpc/rpc.h>\fR +.fi +.in -2 +.sp + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_auth(const SVCXPRT *\fIxprt\fR, const enum auth_stat +\fIwhy\fR);\fR +.ad +.sp .6 +.RS 4n +Called by a service dispatch routine that refuses to perform a remote procedure +call due to an authentication error. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_decode(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +Called by a service dispatch routine that cannot successfully decode the remote +parameters (see \fBsvc_getargs()\fR in \fBrpc_svc_reg\fR(3NSL)). +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_noproc(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +Called by a service dispatch routine that does not implement the procedure +number that the caller requests. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_noprog(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +Called when the desired program is not registered with the \fBRPC\fR package. +Service implementors usually do not need this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_progvers(const SVCXPRT *\fIxprt\fR, const rpcvers_t +\fIlow_vers\fR, const rpcvers_t \fIhigh_vers\fR);\fR +.ad +.sp .6 +.RS 4n +Called when the desired version of a program is not registered with the +\fBRPC\fR package. \fIlow_vers\fR is the lowest version number, and +\fIhigh_vers\fR is the highest version number. Service implementors usually do +not need this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_systemerr(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +Called by a service dispatch routine when it detects a system error not covered +by any particular protocol. For example, if a service can no longer allocate +storage, it may call this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svcerr_weakauth(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +Called by a service dispatch routine that refuses to perform a remote procedure +call due to insufficient (but correct) authentication parameters. The routine +calls \fBsvcerr_auth(xprt, AUTH_TOOWEAK)\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL), +\fBrpc_svc_reg\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_svc_input.3nsl b/usr/src/man/man3nsl/rpc_svc_input.3nsl new file mode 100644 index 0000000000..a5b2c10ea3 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_svc_input.3nsl @@ -0,0 +1,162 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_svc_input 3NSL "6 Jan 2003" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_svc_input, svc_add_input, svc_remove_input \- declare or remove a callback +on a file descriptor +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpc.h> + +\fBtypedef void (*\fR\fBsvc_callback_t\fR)(\fBsvc_input_id_t\fR \fIid\fR, \fBint\fR \fIfd\fR, + \fBunsigned int\fR \fIevents\fR, \fBvoid *\fR\fIcookie\fR); +.fi + +.LP +.nf +\fBsvc_input_id_t\fR \fBsvc_add_input\fR(\fBint\fR \fIfd\fR, \fBunsigned int\fR \fIrevents\fR, + \fBsvc_callback_t\fR \fIcallback\fR, \fBvoid *\fR\fIcookie\fR); +.fi + +.LP +.nf +\fBint\fR \fBsvc_remove_input\fR(\fBsvc_input_t\fR \fIid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The following RPC routines are used to declare or remove a callback on a file +descriptor. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure. +.sp +.ne 2 +.mk +.na +\fBsvc_add_input\fB()\fR\fR +.ad +.RS 22n +.rt +This function is used to register a \fIcallback\fR function on a file +descriptor, \fIfd\fR. The file descriptor, \fIfd\fR, is the first parameter to +be passed to \fBsvc_add_input()\fR. This \fIcallback\fR function will be +automatically called if any of the events specified in the \fIevents\fR +parameter occur on this descriptor. The \fIevents\fR parameter is used to +specify when the callback is invoked. This parameter is a mask of poll events +to which the user wants to listen. See \fBpoll\fR(2) for further details of the +events that can be specified. +.sp +The callback to be invoked is specified using the \fIcallback\fR parameter. The +\fIcookie\fR parameter can be used to pass any data to the \fIcallback\fR +function. This parameter is a user-defined value which is passed as an argument +to the \fIcallback\fR function, and it is not used by the Sun RPC library +itself. +.sp +Several callbacks can be registered on the same file descriptor as long as each +callback registration specifies a separate set of event flags. +.sp +The \fIcallback\fR function is called with the registration \fIid\fR, the +\fIfd\fR file descriptor, an \fIrevents\fR value, which is a bitmask of all +events concerning the file descriptor, and the \fIcookie\fR user-defined value. +.sp +Upon successful completion, the function returns a unique identifier for this +registration, that can be used later to remove this callback. Upon failure, +\fB-1\fR is returned and \fBerrno\fR is set to indicate the error. +.sp +The \fBsvc_add_input()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIfd\fR or \fIevents\fR parameters are invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEEXIST\fR\fR +.ad +.RS 10n +.rt +A callback is already registered to the file descriptor with one of the +specified events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Memory is exhausted. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsvc_remove_input()\fR\fR +.ad +.RS 22n +.rt +This function is used to unregister a callback function on a file descriptor, +\fIfd\fR. The \fIid\fR parameter specifies the registration to be removed. +.sp +Upon successful completion, the function returns zero. Upon failure, \fB-1\fR +is returned and \fBerrno\fR is set to indicate the error. +.sp +The \fBsvc_remove_input()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 10n +.rt +The \fIid\fR parameter is invalid. +.RE + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitectureAll +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBrpc\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_svc_reg.3nsl b/usr/src/man/man3nsl/rpc_svc_reg.3nsl new file mode 100644 index 0000000000..6ceaa118ce --- /dev/null +++ b/usr/src/man/man3nsl/rpc_svc_reg.3nsl @@ -0,0 +1,169 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1995 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_svc_reg 3NSL "20 Feb 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_svc_reg, rpc_reg, svc_reg, svc_unreg, svc_auth_reg, xprt_register, +xprt_unregister \- library routines for registering servers +.SH DESCRIPTION +.sp +.LP +These routines are a part of the \fBRPC\fR library which allows the \fBRPC\fR +servers to register themselves with \fBrpcbind()\fR (see \fBrpcbind\fR(1M)), +and associate the given program and version number with the dispatch function. +When the RPC server receives a RPC request, the library invokes the dispatch +routine with the appropriate arguments. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure. +.sp +.in +2 +.nf +\fB#include <rpc/rpc.h>\fR +.fi +.in -2 +.sp + +.sp +.ne 2 +.mk +.na +\fBbool_t rpc_reg(const rpcprog_t \fIprognum\fR, const rpcvers_t \fIversnum\fR, +const rpcproc_t \fIprocnum\fR, char * (*\fIprocname\fR)(\|), const xdrproc_t +\fIinproc\fR, const xdrproc_t \fIoutproc\fR, const char *\fInettype\fR);\fR +.ad +.sp .6 +.RS 4n +Register program \fIprognum\fR, procedure \fIprocname\fR, and version +\fIversnum\fR with the \fBRPC\fR service package. If a request arrives for +program \fIprognum\fR, version \fIversnum\fR, and procedure \fIprocnum\fR, +\fIprocname\fR is called with a pointer to its parameter(s); \fIprocname\fR +should return a pointer to its \fBstatic\fR result(s). The \fIarg\fR parameter +to \fIprocname\fR is a pointer to the (decoded) procedure argument. +\fIinproc\fR is the XDR function used to decode the parameters while +\fIoutproc\fR is the XDR function used to encode the results. Procedures are +registered on all available transports of the class \fInettype\fR. See +\fBrpc\fR(3NSL). This routine returns \fB0\fR if the registration succeeded, +\fB\(mi1\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBint svc_reg(const SVCXPRT *\fIxprt\fR, const rpcprog_t \fIprognum\fR, const +rpcvers_t \fIversnum\fR, const void (*\fIdispatch\fR)(\|), const struct +netconfig *\fInetconf\fR);\fR +.ad +.sp .6 +.RS 4n +Associates \fIprognum\fR and \fIversnum\fR with the service dispatch procedure, +\fIdispatch\fR. If \fInetconf\fR is \fINULL\fR, the service is not registered +with the \fBrpcbind\fR service. For example, if a service has already been +registered using some other means, such as \fBinetd\fR (see \fBinetd\fR(1M)), +it will not need to be registered again. If \fInetconf\fR is non-zero, then a +mapping of the triple [\fIprognum\fR, \fI versnum\fR, \fInetconf\fR->\fI]\fR to +\fIxprt\fR-> \fIxp_ltaddr\fR is established with the local \fBrpcbind\fR +service. +.sp +The \fBsvc_reg()\fR routine returns \fB1\fR if it succeeds, and \fB0\fR +otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid svc_unreg(const rpcprog_t \fIprognum\fR, const rpcvers_t +\fIversnum\fR);\fR +.ad +.sp .6 +.RS 4n +Remove from the \fBrpcbind\fR service, all mappings of the triple +[\fIprognum\fR, \fIversnum\fR, \fIall-transports\fR] to network address and all +mappings within the RPC service package of the double [\fIprognum\fR, +\fIversnum\fR] to dispatch routines. +.RE + +.sp +.ne 2 +.mk +.na +\fBint svc_auth_reg(const int \fIcred_flavor\fR, const enum auth_stat +(*handler)(\|));\fR +.ad +.sp .6 +.RS 4n +Registers the service authentication routine \fIhandler\fR with the dispatch +mechanism so that it can be invoked to authenticate RPC requests received with +authentication type \fIcred_flavor\fR. This interface allows developers to add +new authentication types to their RPC applications without needing to modify +the libraries. Service implementors usually do not need this routine. +.sp +Typical service application would call \fBsvc_auth_reg()\fR after registering +the service and prior to calling \fBsvc_run()\fR. When needed to process an RPC +credential of type \fIcred_flavor\fR, the \fIhandler\fR procedure will be +called with two parameters \fB (struct svc_req *\fR\fIrqst\fR\fB,\fR \fBstruct +rpc_msg *\fR\fImsg\fR\fB)\fR and is expected to return a valid \fBenum +auth_stat\fR value. There is no provision to change or delete an authentication +handler once registered. +.sp +The \fBsvc_auth_reg()\fR routine returns \fB0\fR if the registration is +successful, \fB1\fR if \fIcred_flavor\fR already has an authentication handler +registered for it, and \fB\(mi1\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid xprt_register(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +After \fBRPC\fR service transport handle \fIxprt\fR is created, it is +registered with the \fBRPC\fR service package. This routine modifies the global +variable \fBsvc_fdset\fR (see \fBrpc_svc_calls\fR(3NSL)). Service implementors +usually do not need this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid xprt_unregister(const SVCXPRT *\fIxprt\fR);\fR +.ad +.sp .6 +.RS 4n +Before an \fBRPC\fR service transport handle \fIxprt\fR is destroyed, it +unregisters itself with the \fBRPC\fR service package. This routine modifies +the global variable \fBsvc_fdset\fR (see \fBrpc_svc_calls\fR(3NSL)). Service +implementors usually do not need this routine. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBinetd\fR(1M), \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_svc_calls\fR(3NSL), +\fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpcbind\fR(3NSL), +\fBselect\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpc_xdr.3nsl b/usr/src/man/man3nsl/rpc_xdr.3nsl new file mode 100644 index 0000000000..0806eda168 --- /dev/null +++ b/usr/src/man/man3nsl/rpc_xdr.3nsl @@ -0,0 +1,178 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 1988 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpc_xdr 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpc_xdr, xdr_accepted_reply, xdr_authsys_parms, xdr_callhdr, xdr_callmsg, +xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for +remote procedure calls +.SH SYNOPSIS +.LP +.nf +\fBbool_t\fR \fBxdr_accepted_reply\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst struct accepted_reply *\fR\fIar\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_authsys_parms\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct authsys_parms *\fR\fIaupp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBxdr_callhdr\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct rpc_msg *\fR\fIchdr\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_callmsg\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct rpc_msg *\fR\fIcmsg\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_opaque_auth\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct opaque_auth *\fR\fIap\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_rejected_reply\fR(\fBXDR *\fR\fIxdrs\fR, \fB const struct rejected_reply *\fR\fIrr\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_replymsg\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst struct rpc_msg *\fR\fIrmsg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These routines are used for describing the \fBRPC\fR messages in \fBXDR\fR +language. They should normally be used by those who do not want to use the +\fBRPC\fR package directly. These routines return TRUE if they succeed, FALSE +otherwise. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. +.sp +.in +2 +.nf + #include <rpc/rpc.h> +.fi +.in -2 +.sp + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_accepted_reply()\fR\fR +.ad +.RS 24n +.rt +Used to translate between \fBRPC\fR reply messages and their external +representation. It includes the status of the \fBRPC\fR call in the \fBXDR\fR +language format. In the case of success, it also includes the call results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_authsys_parms()\fR\fR +.ad +.RS 24n +.rt +Used for describing \fBUNIX\fR operating system credentials. It includes +machine-name, uid, gid list, etc. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_callhdr()\fR\fR +.ad +.RS 24n +.rt +Used for describing \fBRPC\fR call header messages. It encodes the static part +of the call message header in the \fBXDR\fR language format. It includes +information such as transaction \fBID,\fR \fBRPC\fR version number, program and +version number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_callmsg()\fR\fR +.ad +.RS 24n +.rt +Used for describing \fBRPC\fR call messages. This includes all the \fBRPC\fR +call information such as transaction \fBID,\fR \fBRPC\fR version number, +program number, version number, authentication information, etc. This is +normally used by servers to determine information about the client \fBRPC\fR +call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_opaque_auth()\fR\fR +.ad +.RS 24n +.rt +Used for describing \fBRPC\fR opaque authentication information messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_rejected_reply()\fR\fR +.ad +.RS 24n +.rt +Used for describing \fBRPC\fR reply messages. It encodes the rejected \fBRPC\fR +message in the \fBXDR\fR language format. The message could be rejected either +because of version number mis-match or because of authentication errors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_replymsg()\fR\fR +.ad +.RS 24n +.rt +Used for describing \fBRPC\fR reply messages. It translates between the +\fBRPC\fR reply message and its external representation. This reply could be +either an acceptance, rejection or \fINULL\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBxdr\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpcbind.3nsl b/usr/src/man/man3nsl/rpcbind.3nsl new file mode 100644 index 0000000000..c2a40b53fe --- /dev/null +++ b/usr/src/man/man3nsl/rpcbind.3nsl @@ -0,0 +1,192 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpcbind 3NSL "20 Feb 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpcbind, rpcb_getmaps, rpcb_getaddr, rpcb_gettime, rpcb_rmtcall, rpcb_set, +rpcb_unset \- library routines for RPC bind service +.SH SYNOPSIS +.LP +.nf +#include <rpc/rpc.h> + + + +\fBstruct rpcblist *\fR\fBrpcb_getmaps\fR(\fBconst struct netconfig *\fR\fInnetconf\fR, + \fBconst char *\fR\fIhost\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBrpcb_getaddr\fR(\fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst struct netconfig *\fR\fInetconf\fR, \fBstruct netbuf *\fR\fIssvcaddr\fR, + \fBconst char *\fR\fIhost\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBrpcb_gettime\fR(\fBconst char *\fR\fIhost\fR, \fBtime_t *\fR\fItimep\fR); +.fi + +.LP +.nf +\fBenum clnt_stat\fR \fBrpcb_rmtcall\fR(\fBconst struct netconfig *\fR\fInetconf\fR, + \fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR, + \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst rpcproc_t\fR \fIprocnum\fR, + \fBconst xdrproc_t\fR \fIinproc\fR, \fBconst caddr_t\fR \fIin\fR, + \fBconst xdrproc_t\fR \fIoutproc\fR \fBcaddr_t\fR \fIout\fR,, + \fBconst struct timeval\fR \fItout\fR, \fBstruct netbuf *\fR\fIsvcaddr\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBrpcb_set\fR(\fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst struct netconfig *\fR\fInetconf\fR, \fBconst struct netbuf *\fR\fIsvcaddr\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBrpcb_unset\fR(\fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR, + \fBconst struct netconfig *\fR\fInetconf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These routines allow client C programs to make procedure calls to the RPC +binder service. \fBrpcbind\fR maintains a list of mappings between programs and +their universal addresses. See \fBrpcbind\fR(1M). +.SS "Routines" +.sp +.ne 2 +.mk +.na +\fB\fBrpcb_getmaps()\fR\fR +.ad +.RS 18n +.rt +An interface to the \fBrpcbind\fR service, which returns a list of the current +\fBRPC\fR program-to-address mappings on \fIhost\fR. It uses the transport +specified through \fInetconf\fR to contact the remote \fBrpcbind\fR service on +\fIhost\fR. This routine will return \fBNULL,\fR if the remote \fBrpcbind\fR +could not be contacted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpcb_getaddr()\fR\fR +.ad +.RS 18n +.rt +An interface to the \fBrpcbind\fR service, which finds the address of the +service on \fIhost\fR that is registered with program number \fIprognum\fR, +version \fIversnum\fR, and speaks the transport protocol associated with +\fInetconf\fR. The address found is returned in \fIsvcaddr\fR. \fIsvcaddr\fR +should be preallocated. This routine returns \fBTRUE\fR if it succeeds. A +return value of \fBFALSE\fR means that the mapping does not exist or that the +\fBRPC\fR system failed to contact the remote \fBrpcbind\fR service. In the +latter case, the global variable \fBrpc_createerr\fR contains the \fBRPC\fR +status. See \fBrpc_clnt_create\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpcb_gettime()\fR\fR +.ad +.RS 18n +.rt +This routine returns the time on \fIhost\fR in \fItimep\fR. If \fIhost\fR is +\fINULL\fR, \fBrpcb_gettime()\fR returns the time on its own machine. This +routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR if it fails. +\fBrpcb_gettime()\fR can be used to synchronize the time between the client and +the remote server. This routine is particularly useful for secure RPC. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpcb_rmtcall()\fR\fR +.ad +.RS 18n +.rt +An interface to the \fBrpcbind\fR service, which instructs \fBrpcbind\fR on +\fIhost\fR to make an \fBRPC\fR call on your behalf to a procedure on that +host. The \fBnetconfig\fR structure should correspond to a connectionless +transport. The parameter \fB*\fR\fIsvcaddr\fR will be modified to the server's +address if the procedure succeeds. See \fBrpc_call()\fR and \fBclnt_call()\fR +in \fBrpc_clnt_calls\fR(3NSL) for the definitions of other parameters. +.sp +This procedure should normally be used for a "ping" and nothing else. This +routine allows programs to do lookup and call, all in one step. +.sp +Note: Even if the server is not running \fBrpcbind\fR does not return any error +messages to the caller. In such a case, the caller times out. +.sp +Note: \fBrpcb_rmtcall()\fR is only available for connectionless transports. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpcb_set()\fR\fR +.ad +.RS 18n +.rt +An interface to the \fBrpcbind\fR service, which establishes a mapping between +the triple [\fIprognum\fR, \fIversnum\fR, \fInetconf\fR->\fInc_netid]\fR and +\fIsvcaddr\fR on the machine's \fBrpcbind\fR service. The value of +\fInc_netid\fR must correspond to a network identifier that is defined by the +netconfig database. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. See also \fBsvc_reg()\fR in \fBrpc_svc_calls\fR(3NSL). If there +already exists such an entry with \fBrpcbind\fR, \fBrpcb_set()\fR will fail. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpcb_unset()\fR\fR +.ad +.RS 18n +.rt +An interface to the \fBrpcbind\fR service, which destroys the mapping between +the triple [\fIprognum\fR, \fIversnum\fR, \fInetconf\fR->\fInc_netid]\fR and +the address on the machine's \fBrpcbind\fR service. If \fInetconf\fR is +\fINULL\fR, \fBrpcb_unset()\fR destroys all mapping between the triple +[\fIprognum\fR, \fIversnum\fR, \fIall-transports\fR] and the addresses on the +machine's \fBrpcbind\fR service. This routine returns \fBTRUE\fR if it +succeeds, \fBFALSE\fR otherwise. Only the owner of the service or the +super-user can destroy the mapping. See also \fBsvc_unreg()\fR in +\fBrpc_svc_calls\fR(3NSL). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpcbind\fR(1M), \fBrpcinfo\fR(1M), \fBrpc_clnt_calls\fR(3NSL), +\fBrpc_clnt_create\fR(3NSL), \fBrpc_svc_calls\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/rpcsec_gss.3nsl b/usr/src/man/man3nsl/rpcsec_gss.3nsl new file mode 100644 index 0000000000..c5de52cab2 --- /dev/null +++ b/usr/src/man/man3nsl/rpcsec_gss.3nsl @@ -0,0 +1,464 @@ +'\" te +.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rpcsec_gss 3NSL "29 Jun 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +rpcsec_gss \- security flavor incorporating GSS-API protections +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... -lnsl [ \fIlibrary\fR... ] +#include <rpc/rpcsec_gss.h> +.fi + +.SH DESCRIPTION +.sp +.LP +\fBRPCSEC_GSS\fR is a security flavor which sits "on top" of the \fBGSS-API\fR +(Generic Security Service API) for network transmissions. Applications using +\fBRPCSEC_GSS\fR can take advantage of \fBGSS-API\fR security features; +moreover, they can use any security mechanism (such as RSA public key or +Kerberos) that works with the \fBGSS-API.\fR +.sp +.LP +The \fBGSS-API\fR offers two security services beyond the traditional +authentication services \fB(AUTH_DH,\fR \fBAUTH_SYS,\fR and \fBAUTH_KERB):\fR +integrity and privacy. With integrity, the system uses cryptographic +checksumming to ensure the authenticity of a message (authenticity of +originator, recipient, and data); privacy provides additional security by +encrypting data. Applications using \fBRPCSEC_GSS\fR specify which service +they wish to use. Type of security service is mechanism-independent. +.sp +.LP +Before exchanging data with a peer, an application must establish a context for +the exchange. \fBRPCSEC_GSS\fR provides a single function for this purpose, +\fBrpc_gss_seccreate()\fR, which allows the application to specify the security +mechanism, Quality of Protection (QOP), and type of service at context +creation. (The QOP parameter sets the cryptographic algorithms to be used with +integrity or privacy, and is mechanism-dependent.) Once a context is +established, applications can reset the QOP and type of service for each data +unit exchanged, if desired. +.sp +.LP +Valid mechanisms and QOPs may be obtained from configuration files or from the +name service. Each mechanism has a default QOP. +.sp +.LP +Contexts are destroyed with the usual RPC \fBauth_destroy()\fR call. +.SS "Data Structures" +.sp +.LP +Some of the data structures used by the \fBRPCSEC_GSS\fR package are shown +below. +.SS "\fBrpc_gss_service_t\fR" +.sp +.LP +This enum defines the types of security services the context may have. +\fBrpc_gss_seccreate()\fR takes this as one argument when setting the service +type for a session. +.sp +.in +2 +.nf +typedef enum { + rpc_gss_svc_default = 0, + rpc_gss_svc_none = 1, + rpc_gss_svc_integrity = 2, + rpc_gss_svc_privacy = 3 +} rpc_gss_service_t ; +.fi +.in -2 + +.SS "\fBrpc_gss_options_req_t\fR" +.sp +.LP +Structure containing options passed directly through to the \fBGSS-API.\fR +\fBrpc_gss_seccreate()\fR takes this as an argument when creating a context. +.sp +.in +2 +.nf +typedef struct { + int req_flags; /*GSS request bits */ + int time_req; /*requested credential lifetime */ + gss_cred_id_t my_cred; /*GSS credential struct*/ + gss_channel_bindings_t; + input_channel_bindings; +} rpc_gss_options_req_t ; +.fi +.in -2 + +.SS "\fBrpc_gss_OID\fR" +.sp +.LP +This data type is used by in-kernel RPC routines, and thus is mentioned here +for informational purposes only. +.sp +.in +2 +.nf +typedef struct { + u_int length; + void *elements +} *rpc_gss_OID; +.fi +.in -2 + +.SS "\fBrpc_gss_options_ret_t\fR" +.sp +.LP +Structure containing \fBGSS-API\fR options returned to the calling function, +\fBrpc_gss_seccreate()\fR. \fBMAX_GSS_MECH\fR is defined as 128. +.sp +.in +2 +.nf +typedef struct { + int major_status; + int minor_status; + u_int rpcsec_version /*vers. of RPCSEC_GSS */ + int ret_flags + int time_req + gss_ctx_id_t gss_context; + char actual_mechanism[MAX_GSS_MECH]; /*mechanism used*/ +} rpc_gss_options_ret_t; +.fi +.in -2 + +.SS "\fBrpc_gss_principal_t\fR" +.sp +.LP +The (mechanism-dependent, opaque) client principal type. Used as an argument +to the \fBrpc_gss_get_principal_name()\fR function, and in the \fBgsscred\fR +table. Also referenced by the \fBrpc_gss_rawcred_t\fR structure for raw +credentials (see below). +.sp +.in +2 +.nf +typedef struct { + int len; + char name[1]; +} *rpc_gss_principal_t; +.fi +.in -2 + +.SS "\fBrpc_gss_rawcred_t\fR" +.sp +.LP +Structure for raw credentials. Used by \fBrpc_gss_getcred()\fR and +\fBrpc_gss_set_callback()\fR. +.sp +.in +2 +.nf +typedef struct { + u_int version; /*RPC version # */ + char *mechanism; /*security mechanism*/ + char *qop; /*Quality of Protection*/ + rpc_gss_principal_t client_principal; /*client name*/ + char *svc_principal; /*server name*/ + rpc_gss_service_t service; /*service (integrity, etc.)*/ +} rpc_gss_rawcred_t; +.fi +.in -2 + +.SS "\fBrpc_gss_ucred_t\fR" +.sp +.LP +Structure for UNIX credentials. Used by \fBrpc_gss_getcred()\fR as an +alternative to \fBrpc_gss_rawcred_t\fR. +.sp +.in +2 +.nf +typedef struct { + uid_t uid; /*user ID*/ + gid_t gid; /*group ID*/ + short gidlen; + git_t *gidlist; /*list of groups*/ +} rpc_gss_ucred_t; +.fi +.in -2 + +.SS "\fBrpc_gss_callback_t\fR" +.sp +.LP +Callback structure used by \fBrpc_gss_set_callback()\fR. +.sp +.in +2 +.nf +typedef struct { + u_int program; /*RPC program #*/ + u_int version; /*RPC version #*/ + bool_t (*callback)(); /*user-defined callback routine*/ +} rpc_gss_callback_t; +.fi +.in -2 + +.SS "\fBrpc_gss_lock_t\fR" +.sp +.LP +Structure used by a callback routine to enforce a particular QOP and service +for a session. The \fBlocked\fR field is normally set to \fBFALSE;\fR the +server sets it to \fBTRUE\fR in order to lock the session. (A locked context +will reject all requests having different QOP and service values than those +found in the \fBraw_cred\fR structure.) For more information, see the +\fBrpc_gss_set_callback\fR(3NSL) man page. +.sp +.in +2 +.nf +typedef struct { + bool_t locked; + rpc_gss_rawcred_t *raw_cred; +} rpc_gss_lock_t; +.fi +.in -2 + +.SS "\fBrpc_gss_error_t\fR" +.sp +.LP +Structure used by \fBrpc_gss_get_error()\fR to fetch an error code when a +\fBRPCSEC_GSS\fR routine fails. +.sp +.in +2 +.nf +typedef struct { + int rpc_gss_error; + int system_error; /*same as errno*/ +} rpc_gss_error_t; +.fi +.in -2 + +.SS "Index to Routines" +.sp +.LP +The following lists \fBRPCSEC_GSS\fR routines and the manual reference pages +on which they are described. An (S) indicates it is a server-side function: +.sp +.ne 2 +.mk +.na +\fB\fBRoutine\fR (Manual Page) \fR +.ad +.sp .6 +.RS 4n +\fBDescription\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_seccreate\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Create a secure \fBRPCSEC_GSS\fR context +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_set_defaults\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Switch service, QOP for a session +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_max_data_length\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get maximum data length allowed by transport +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_set_svc_name\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Set server's principal name (S) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_getcred\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get credentials of caller (S) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_set_callback\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Specify callback to see context use (S) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_principal_name\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get client principal name (S) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_svc_max_data_length\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get maximum data length allowed by transport (S) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_error\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get error number +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_mechanisms\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get valid mechanism strings +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_mech_info\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get valid QOP strings, current service +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_get_versions\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Get supported \fBRPCSEC_GSS\fR versions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_is_installed\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Checks if a mechanism is installed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_mech_to_oid\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Maps ASCII mechanism to OID representation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrpc_gss_qop_to_num\fR(3NSL) \fR +.ad +.sp .6 +.RS 4n +Maps ASCII QOP, mechansim to u_int number +.RE + +.SS "Utilities" +.sp +.LP +The \fBgsscred\fR utility manages the \fBgsscred\fR table, which contains +mappings of principal names between network and local credentials. See +\fBgsscred\fR(1M). +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/mech\fR \fR +.ad +.RS 18n +.rt +List of installed mechanisms +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/gss/qop\fR \fR +.ad +.RS 18n +.rt +List of valid QOPs +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ + +.SH SEE ALSO +.sp +.LP +\fBgsscred\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), \fBxdr\fR(3NSL), \fBattributes\fR(5), \fBenviron\fR(5) +.sp +.LP +\fIONC+ Developer\&'s Guide\fR +.sp +.LP +Linn, J. \fIRFC 2743, Generic Security Service Application Program Interface Version 2, Update 1\fR. Network Working Group. January 2000. diff --git a/usr/src/man/man3nsl/secure_rpc.3nsl b/usr/src/man/man3nsl/secure_rpc.3nsl new file mode 100644 index 0000000000..0ac38662e9 --- /dev/null +++ b/usr/src/man/man3nsl/secure_rpc.3nsl @@ -0,0 +1,389 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH secure_rpc 3NSL "19 Feb 2004" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +secure_rpc, authdes_getucred, authdes_seccreate, getnetname, host2netname, +key_decryptsession, key_encryptsession, key_gendes, key_setsecret, +key_secretkey_is_set, netname2host, netname2user, user2netname \- library +routines for secure remote procedure calls +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...] +#include <rpc/rpc.h> +#include <sys/types.h> +\fBint\fR \fBauthdes_getucred\fR(\fBconst struct authdes_cred *\fR\fIadc\fR, \fBuid_t *\fR\fIuidp\fR, + \fBgid_t *\fR\fIgidp\fR, \fBshort *\fR\fIgidlenp\fR, \fBgid_t *\fR\fIgidlist\fR); +.fi + +.LP +.nf +\fBAUTH *\fR\fBauthdes_seccreate\fR(\fBconst char *\fR\fIname\fR, \fBconst uint_t\fR \fIwindow\fR, + \fBconst char *\fR\fItimehost\fR, \fIckey\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetnetname\fR(\fBchar\fR \fIname\fR \fB[MAXNETNAMELEN+1]\fR); +.fi + +.LP +.nf +\fBint\fR \fBhost2netname\fR(\fBchar\fR \fIname\fR \fB[MAXNETNAMELEN+1]\fR, \fBconst char *\fR\fIhost\fR, + \fBconst char *\fR\fIdomain\fR); +.fi + +.LP +.nf +\fBint\fR \fBkey_decryptsession\fR(\fBconst char *\fR\fIremotename\fR, \fBdes_block *\fR\fIdeskey\fR); +.fi + +.LP +.nf +\fBint\fR \fBkey_encryptsession\fR(\fBconst char *\fR\fIremotename\fR, \fBdes_block *\fR\fIdeskey\fR); +.fi + +.LP +.nf +\fBint\fR \fBkey_gendes\fR(\fBdes_block *\fR\fIdeskey\fR); +.fi + +.LP +.nf +\fBint\fR \fBkey_setsecret\fR(\fBconst char *\fR\fIkey\fR); +.fi + +.LP +.nf +\fBint\fR \fBkey_secretkey_is_set\fR(void) +.fi + +.LP +.nf +\fBint\fR \fBnetname2host\fR(\fBconst char *\fR\fIname\fR, \fBchar *\fR\fIhost\fR, \fBconst int\fR \fIhostlen\fR); +.fi + +.LP +.nf +\fBint\fR \fBnetname2user\fR(\fBconst char *\fR\fIname\fR, \fBuid_t *\fR\fIuidp\fR, \fBgid_t *\fR\fIgidp\fR, \fBint *\fR\fIgidlenp\fR, + \fBgid_t *\fR\fIgidlist\fR \fB[NGRPS]\fR); +.fi + +.LP +.nf +\fBint\fR \fBuser2netname\fR(\fBchar\fR \fIname\fR \fB[MAXNETNAMELEN+1]\fR, \fBconst uid_t\fR \fIuid\fR, + \fBconst char *\fR\fIdomain\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBRPC\fR library functions allow C programs to make procedure calls on +other machines across the network. +.sp +.LP +\fBRPC\fR supports various authentication flavors. Among them are: +.sp +.ne 2 +.mk +.na +\fB\fBAUTH_NONE\fR\fR +.ad +.RS 13n +.rt +No authentication (none). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAUTH_SYS\fR\fR +.ad +.RS 13n +.rt +Traditional \fBUNIX-style\fR authentication. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAUTH_DES\fR\fR +.ad +.RS 13n +.rt +\fBDES\fR encryption-based authentication. +.RE + +.sp +.LP +The \fBauthdes_getucred()\fR and \fBauthdes_seccreate()\fR functions implement +the \fBAUTH_DES\fR authentication style. The keyserver daemon \fBkeyserv\fR(1M) +must be running for the \fBAUTH_DES\fR authentication system to work and +\fBkeylogin\fR(1) must have been run. The \fBAUTH_DES\fR style of +authentication is discussed here. For information about the \fBAUTH_NONE\fR and +\fBAUTH_SYS\fR flavors of authentication, refer to \fBrpc_clnt_auth\fR(3NSL). +See \fBrpc\fR(3NSL) for the definition of the \fBAUTH\fR data structure. +.sp +.LP +The following functions documented on this page are MT-Safe. For the MT-levels +of other authentication styles, see relevant man pages. +.sp +.ne 2 +.mk +.na +\fB\fBauthdes_getucred()\fR\fR +.ad +.RS 26n +.rt +This is the first of two functions that interface to the \fBRPC\fR secure +authentication system \fBAUTH_DES\fR. The second is the +\fBauthdes_seccreate()\fR function. The \fBauthdes_getucred()\fR function is +used on the server side to convert an \fBAUTH_DES\fR credential, which is +operating system independent, to an \fBAUTH_SYS\fR credential. The +\fBauthdes_getucred()\fR function returns \fB1\fR if it succeeds, \fB0\fR if it +fails. +.sp +The \fB*\fR\fIuidp\fR parameter is set to the user's numerical \fBID\fR +associated with \fIadc\fR. The \fB*\fR\fIgidp\fR parameter is set to the +numerical \fBID\fR of the user's group. The \fB*\fR\fIgidlist\fR parameter +contains the numerical \fBIDs\fR of the other groups to which the user belongs. +The \fB*\fR\fIgidlenp\fR parameter is set to the number of valid group ID +entries specified by the \fB*\fR\fIgidlist\fR parameter. +.sp +The \fBauthdes_getucred()\fR function fails if the \fBauthdes_cred\fR structure +was created with the netname of a host. In such a case, \fBnetname2host()\fR +should be used to get the host name from the host netname in the +\fBauthdes_cred\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauthdes_seccreate()\fR\fR +.ad +.RS 26n +.rt +The second of two \fBAUTH_DES\fR authentication functions, the +\fBauthdes_seccreate()\fR function is used on the client side to return an +authentication handle that enables the use of the secure authentication system. +The first field, \fIname\fR, specifies the network name \fInetname\fR of the +owner of the server process. The field usually represents a hostname derived +from the \fBhost2netname()\fR utility, but the field might also represent a +user name converted with the \fBuser2netname()\fR utility. +.sp +The second field, \fIwindow\fR, specifies the validity of the client credential +in seconds. If the difference in time between the client's clock and the +server's clock exceeds \fIwindow\fR, the server rejects the client's +credentials and the clock will have to be resynchronized. A small window is +more secure than a large one, but choosing too small a window increases the +frequency of resynchronization due to clock drift. +.sp +The third parameter, \fItimehost\fR, is the host's name and is optional. If +\fItimehost\fR is \fINULL\fR, the authentication system assumes that the local +clock is always in sync with the \fItimehost\fR clock and does not attempt +resynchronization. If a timehost is supplied, the system consults the remote +time service whenever resynchronization is required. The \fItimehost\fR +parameter is usually the name of the host on which the server is running. +.sp +The final parameter, \fIckey\fR, is also optional. If \fIckey\fR is \fINULL,\fR +the authentication system generates a random \fBDES\fR key to be used for the +encryption of credentials. If \fIckey\fR is supplied, it is used for +encryption. +.sp +If \fBauthdes_seccreate()\fR fails, it returns \fINULL.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgetnetname()\fR\fR +.ad +.RS 26n +.rt +This function returns the unique, operating system independent netname of the +caller in the fixed-length array \fIname\fR. The function returns \fB1\fR if it +succeeds and \fB0\fR if it fails. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhost2netname()\fR\fR +.ad +.RS 26n +.rt +This function converts a domain-specific hostname \fIhost\fR to an operating +system independent netname. The function returns \fB1\fR if it succeeds and +\fB0\fR if it fails. The \fBhost2netname()\fR function is the inverse of the +\fBnetname2host()\fR function. If the \fIdomain\fR is \fINULL\fR, +\fBhost2netname()\fR uses the default domain name of the machine. If \fIhost\fR +is \fINULL\fR, it defaults to that machine itself. If \fIdomain\fR is +\fINULL\fR and \fIhost\fR is an NIS name such as \fBmyhost.sun.example.com\fR, +the \fBhost2netname()\fR function uses the domain \fBsun.example.com\fR rather +than the default domain name of the machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_decryptsession()\fR\fR +.ad +.RS 26n +.rt +This function is an interface to the keyserver daemon, which is associated with +\fBRPC's\fR secure authentication system (\fBAUTH_DES\fR authentication). User +programs rarely need to call \fBkey_decryptsession()\fR or the associated +functions \fBkey_encryptsession()\fR, \fBkey_gendes()\fR, and +\fBkey_setsecret()\fR. +.sp +The \fBkey_decryptsession()\fR function takes a server netname \fIremotename\fR +and a \fBDES\fR key \fIdeskey\fR, and decrypts the key by using the the public +key of the server and the secret key associated with the effective \fBUID\fR of +the calling process. The \fBkey_decryptsession()\fR function is the inverse of +\fBkey_encryptsession()\fR function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_encryptsession()\fR\fR +.ad +.RS 26n +.rt +This function is a keyserver interface that takes a server netname +\fIremotename\fR and a \fBDES\fR key \fIdeskey\fR, and encrypts the key using +the public key of the the server and the secret key associated with the +effective \fBUID\fR of the calling process. If the keyserver does not have a +key registered for the UID, it falls back to using the secret key for the +netname \fBnobody\fR unless this feature has been disabled. See +\fBkeyserv\fR(1M). The \fBkey_encryptsession()\fR function is the inverse of +\fBkey_decryptsession()\fR function. The \fBkey_encryptsession()\fR function +returns \fB0\fR if it succeeds, \fB\(mi1\fR if it fails. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_gendes()\fR\fR +.ad +.RS 26n +.rt +This is a keyserver interface function used to ask the keyserver for a secure +conversation key. Selecting a conversion key at random is generally not secure +because the common ways of choosing random numbers are too easy to guess. The +\fBkey_gendes()\fR function returns \fB0\fR if it succeeds, \fB\(mi1\fR if it +fails. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_setsecret()\fR\fR +.ad +.RS 26n +.rt +This is a keyserver interface function used to set the key for the effective +\fBUID\fR of the calling process. This function returns \fB0\fR if it succeeds, +\fB\(mi1\fR if it fails. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkey_secretkey_is_set()\fR\fR +.ad +.RS 26n +.rt +This is a keyserver interface function used to determine if a key has been set +for the effective \fBUID\fR of the calling process. If the keyserver has a key +stored for the effective \fBUID\fR of the calling process, the +\fBkey_secretkey_is_set()\fR function returns \fB1\fR. Otherwise it returns +\fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnetname2host()\fR\fR +.ad +.RS 26n +.rt +This function converts an operating system independent netname \fIname\fR to a +domain-specific hostname \fIhost\fR. The \fIhostlen\fR parameter is the maximum +size of \fIhost\fR. The \fBnetname2host()\fR function returns \fB1\fR if it +succeeds and \fB0\fR if it fails. The function is the inverse of the +\fBhost2netname()\fR function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnetname2user()\fR\fR +.ad +.RS 26n +.rt +This function converts an operating system independent netname to a +domain-specific user \fBID\fR. The \fBnetname2user()\fR function returns +\fB1\fR if it succeeds and \fB0\fR if it fails.The function is the inverse of +the \fBuser2netname()\fR function. +.sp +The \fB*\fR\fIuidp\fR parameter is set to the user's numerical \fBID\fR +associated with \fIname\fR. The \fB*\fR\fIgidp\fR parameter is set to the +numerical \fBID\fR of the user's group. The \fIgidlist\fR parameter contains +the numerical \fBIDs\fR of the other groups to which the user belongs. The +\fB*\fR\fIgidlenp\fR parameter is set to the number of valid group \fBID\fR +entries specified by the \fIgidlist\fR parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuser2netname()\fR\fR +.ad +.RS 26n +.rt +This function converts a domain-specific username to an operating system +independent netname. The \fBuser2netname()\fR function returns \fB1\fR if it +succeeds and \fB0\fR if it fails. The function is the inverse of +\fBnetname2user()\fR function. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBchkey\fR(1), \fBkeylogin\fR(1), \fBkeyserv\fR(1M), \fBnewkey\fR(1M), +\fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_accept.3nsl b/usr/src/man/man3nsl/t_accept.3nsl new file mode 100644 index 0000000000..af6080c428 --- /dev/null +++ b/usr/src/man/man3nsl/t_accept.3nsl @@ -0,0 +1,418 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_accept 3NSL "1 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_accept \- accept a connection request +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_accept\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIresfd\fR, \fBconst struct t_call *\fR\fIcall\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces that evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, a +different header file, \fBtiuser.h\fR, must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is issued by a transport user to accept a connection request. +The parameter \fIfd\fR identifies the local transport endpoint where the +connection indication arrived; \fIresfd\fR specifies the local transport +endpoint where the connection is to be established, and \fIcall\fR contains +information required by the transport provider to complete the connection. The +parameter \fIcall\fR points to a \fBt_call\fR structure which contains the +following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +struct netbuf udata; +int sequence; +.fi +.in -2 + +.sp +.LP +In \fIcall\fR, \fIaddr\fR is the protocol address of the calling transport +user, \fIopt\fR indicates any options associated with the connection, +\fIudata\fR points to any user data to be returned to the caller, and +\fIsequence\fR is the value returned by \fBt_listen\fR(3NSL) that uniquely +associates the response with a previously received connection indication. The +address of the caller, \fIaddr\fR may be null (length zero). Where \fIaddr\fR +is not null then it may optionally be checked by XTI. +.sp +.LP +A transport user may accept a connection on either the same, or on a different, +local transport endpoint than the one on which the connection indication +arrived. Before the connection can be accepted on the same endpoint +(\fIresfd==fd\fR), the user must have responded to any previous connection +indications received on that transport endpoint by means of \fBt_accept()\fR or +\fBt_snddis\fR(3NSL). Otherwise, \fBt_accept()\fR will fail and set +\fBt_errno\fR to \fBTINDOUT\fR. +.sp +.LP +If a different transport endpoint is specified (\fIresfd!=fd\fR), then the user +may or may not choose to bind the endpoint before the \fBt_accept()\fR is +issued. If the endpoint is not bound prior to the \fBt_accept()\fR, the +endpoint must be in the \fBT_UNBND\fR state before the \fBt_accept()\fR is +issued, and the transport provider will automatically bind it to an address +that is appropriate for the protocol concerned. If the transport user chooses +to bind the endpoint it must be bound to a protocol address with a \fIqlen\fR +of zero and must be in the \fBT_IDLE\fR state before the \fBt_accept()\fR is +issued. +.sp +.LP +Responding endpoints should be supplied to \fBt_accept()\fR in the state +\fBT_UNBND.\fR +.sp +.LP +The call to \fBt_accept()\fR may fail with t_errno set to \fBTLOOK\fR if there +are indications (for example connect or disconnect) waiting to be received on +endpoint \fIfd\fR. Applications should be prepared for such a failure. +.sp +.LP +The \fIudata\fR argument enables the called transport user to send user data to +the caller and the amount of user data must not exceed the limits supported by +the transport provider as returned in the \fIconnect\fR field of the \fIinfo\fR +argument of \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). If the \fIlen\fR field +of \fIudata\fR is zero, no data will be sent to the caller. All the +\fImaxlen\fR fields are meaningless. +.sp +.LP +When the user does not indicate any option (\fIcall\(->opt.len\fR = 0) the +connection shall be accepted with the option values currently set for the +responding endpoint \fIresfd\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBfd: T_INCON\fR +.sp +.LP +\fBresfd (fd!=resfd): T_IDLE, T_UNBND\fR +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTACCES\fR\fR +.ad +.RS 17n +.rt +The user does not have permission to accept a connection on the responding +transport endpoint or to use the specified options. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADADDR\fR\fR +.ad +.RS 17n +.rt +The specified protocol address was in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 17n +.rt +The amount of user data specified was not within the bounds allowed by the +transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 17n +.rt +The file descriptor \fIfd\fR or \fIresfd\fR does not refer to a transport +endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADOPT\fR\fR +.ad +.RS 17n +.rt +The specified options were in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADSEQ\fR\fR +.ad +.RS 17n +.rt +Either an invalid sequence number was specified, or a valid sequence number was +specified but the connection request was aborted by the peer. In the latter +case, its \fBT_DISCONNECT\fR event will be received on the listening endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTINDOUT\fR\fR +.ad +.RS 17n +.rt +The function was called with \fIfd==resfd\fR but there are outstanding +connection indications on the endpoint. Those other connection indications +must be handled either by rejecting them by means of \fBt_snddis\fR(3NSL) or +accepting them on a different endpoint by means of \fBt_accept\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 17n +.rt +An asynchronous event has occurred on the transport endpoint referenced by +\fIfd\fR and requires immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 17n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 17n +.rt +The communications endpoint referenced by \fIfd\fR or \fIresfd\fR is not in +one of the states in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 17n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +(\fBt_errno\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROVMISMATCH\fR\fR +.ad +.RS 17n +.rt +The file descriptors \fIfd\fR and \fIresfd\fR do not refer to the same +transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRESADDR\fR\fR +.ad +.RS 17n +.rt +This transport provider requires both \fIfd\fR and \fIresfd\fR to be bound to +the same address. This error results if they are not. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRESQLEN\fR\fR +.ad +.RS 17n +.rt +The endpoint referenced by \fIresfd\fR (where \fIresfd\fR != \fIfd\fR) was +bound to a protocol address with a \fIqlen\fR that is greater than zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 17n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR \fR +.ad +.RS 18n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTINDOUT\fR \fR +.ad +.RS 18n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROVMISMATCH\fR \fR +.ad +.RS 18n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRESADDR\fR \fR +.ad +.RS 18n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRESQLEN\fR \fR +.ad +.RS 18n +.rt + +.RE + +.SS "Option Buffer" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not +specify the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_connect\fR(3NSL), \fBt_getinfo\fR(3NSL), \fBt_getstate\fR(3NSL), +\fBt_listen\fR(3NSL), \fBt_open\fR(3NSL), \fBt_optmgmt\fR(3NSL), +\fBt_rcvconnect\fR(3NSL), \fBt_snddis\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +There may be transport provider-specific restrictions on address binding. +.sp +.LP +Some transport providers do not differentiate between a connection indication +and the connection itself. If the connection has already been established +after a successful return of \fBt_listen\fR(3NSL), \fBt_accept()\fR will assign +the existing connection to the transport endpoint specified by \fIresfd\fR. diff --git a/usr/src/man/man3nsl/t_alloc.3nsl b/usr/src/man/man3nsl/t_alloc.3nsl new file mode 100644 index 0000000000..6b58576517 --- /dev/null +++ b/usr/src/man/man3nsl/t_alloc.3nsl @@ -0,0 +1,300 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_alloc 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_alloc \- allocate a library structure +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBvoid *\fR\fBt_alloc\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIstruct_type\fR, \fBint\fR \fIfields\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, a +different header file, \fBtiuser.h\fR, must be used. Refer to the section, +\fBTLI\fR \fBCOMPATIBILITY\fR, for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_alloc()\fR function dynamically allocates memory for the various +transport function argument structures as specified below. This function will +allocate memory for the specified structure, and will also allocate memory for +buffers referenced by the structure. +.sp +.LP +The structure to allocate is specified by \fIstruct_type\fR and must be one of +the following: +.sp +.in +2 +.nf +T_BIND struct t_bind +T_CALL struct t_call +T_OPTMGMT struct t_optmgmt +T_DIS struct t_discon +T_UNITDATA struct t_unitdata +T_UDERROR struct t_uderr +T_INFO struct t_info +.fi +.in -2 + +.sp +.LP +where each of these structures may subsequently be used as an argument to one +or more transport functions. +.sp +.LP +Each of the above structures, except \fBT_INFO,\fR contains at least one field +of type \fBstruct\fR \fBnetbuf\fR. For each field of this type, the user may +specify that the buffer for that field should be allocated as well. The length +of the buffer allocated will be equal to or greater than the appropriate size +as returned in the \fIinfo\fR argument of \fBt_open\fR(3NSL) or +\fBt_getinfo\fR(3NSL). The relevant fields of the \fIinfo\fR argument are +described in the following list. The \fIfields\fR argument specifies which +buffers to allocate, where the argument is the bitwise-or of any of the +following: +.sp +.ne 2 +.mk +.na +\fB\fBT_ADDR\fR \fR +.ad +.RS 12n +.rt +The \fIaddr\fR field of the \fBt_bind\fR, \fBt_call\fR, \fBt_unitdata\fR or +\fBt_uderr\fR structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OPT\fR \fR +.ad +.RS 12n +.rt +The \fIopt\fR field of the \fBt_optmgmt\fR, \fBt_call\fR, \fBt_unitdata\fR or +\fBt_uderr\fR structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_UDATA\fR \fR +.ad +.RS 12n +.rt +The \fIudata\fR field of the \fBt_call\fR, \fBt_discon\fR or \fBt_unitdata\fR +structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_ALL\fR \fR +.ad +.RS 12n +.rt +All relevant fields of the given structure. Fields which are not supported by +the transport provider specified by \fIfd\fR will not be allocated. +.RE + +.sp +.LP +For each relevant field specified in \fIfields\fR, \fBt_alloc()\fR will +allocate memory for the buffer associated with the field, and initialize the +\fIlen\fR field to zero and the \fIbuf\fR pointer and \fImaxlen\fR field +accordingly. Irrelevant or unknown values passed in fields are ignored. Since +the length of the buffer allocated will be based on the same size information +that is returned to the user on a call to \fBt_open\fR(3NSL) and +\fBt_getinfo\fR(3NSL), \fIfd\fR must refer to the transport endpoint through +which the newly allocated structure will be passed. In the case where a +\fBT_INFO\fR structure is to be allocated, \fIfd\fR may be set to any value. In +this way the appropriate size information can be accessed. If the size value +associated with any specified field is \fBT_INVALID,\fR \fBt_alloc()\fR will +be unable to determine the size of the buffer to allocate and will fail, +setting \fBt_errno\fR to \fBTSYSERR\fR and \fBerrno\fR to \fBEINVAL\fR. See +\fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). If the size value associated with +any specified field is \fBT_INFINITE,\fR then the behavior of \fBt_alloc()\fR +is implementation-defined. For any field not specified in \fIfields\fR, +\fIbuf\fR will be set to the null pointer and \fIlen\fR and \fImaxlen\fR will +be set to zero. See \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). +.sp +.LP +The pointer returned if the allocation succeeds is suitably aligned so that it +can be assigned to a pointer to any type of object and then used to access such +an object or array of such objects in the space allocated. +.sp +.LP +Use of \fBt_alloc()\fR to allocate structures will help ensure the +compatibility of user programs with future releases of the transport interface +functions. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBt_alloc()\fR returns a pointer to the newly +allocated structure. On failure, a null pointer is returned. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 16n +.rt +\fBstruct_type\fR is other than \fBT_INFO\fR and the specified file descriptor +does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOSTRUCTYPE\fR\fR +.ad +.RS 16n +.rt +Unsupported \fIstruct_type\fR requested. This can include a request for a +structure type which is inconsistent with the transport provider type +specified, that is, connection-mode or connectionless-mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 16n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 16n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.LP +\fB#include\fR \fB<tiuser.h>\fR +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR \fR +.ad +.RS 17n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOSTRUCTYPE\fR \fR +.ad +.RS 17n +.rt + +.RE + +.SS "Special Buffer Sizes" +.sp +.LP +Assume that the value associated with any field of \fBstruct\fR \fBt_info\fR +(argument returned by \fBt_open()\fR or \fBt_getinfo()\fR\|) that describes +buffer limits is -1. Then the underlying service provider can support a buffer +of unlimited size. If this is the case, \fBt_alloc()\fR will allocate a buffer +with the default size 1024 bytes, which may be handled as described in the next +paragraph. +.sp +.LP +If the underlying service provider supports a buffer of unlimited size in the +\fBnetbuf\fR structure (see \fBt_connect\fR(3NSL)), \fBt_alloc()\fR will return +a buffer of size 1024 bytes. If a larger size buffer is required, it will need +to be allocated separately using a memory allocation routine such as +\fBmalloc\fR(3C). The \fBbuf\fR and \fBmaxlen\fR fields of the \fBnetbuf\fR +data structure can then be updated with the address of the new buffer and the +1024 byte buffer originally allocated by \fBt_alloc()\fR can be freed using +\fBfree\fR(3C). +.sp +.LP +Assume that the value associated with any field of \fBstruct\fR \fBt_info\fR +(argument returned by \fBt_open()\fR or \fBt_getinfo()\fR \fB\|)\fR that +describes nbuffer limits is \fB-2\fR\&. Then \fBt_alloc()\fR will set the +buffer pointer to \fINULL\fR and the buffer maximum size to \fB0\fR, and then +will return success (see \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL)). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfree\fR(3C), \fBmalloc\fR(3C), \fBt_connect\fR(3NSL), \fBt_free\fR(3NSL), +\fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_bind.3nsl b/usr/src/man/man3nsl/t_bind.3nsl new file mode 100644 index 0000000000..d8b2d180a7 --- /dev/null +++ b/usr/src/man/man3nsl/t_bind.3nsl @@ -0,0 +1,333 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_bind 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_bind \- bind an address to a transport endpoint +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_bind\fR(\fBint\fR \fIfd\fR, \fBconst struct t_bind *\fR\fIreq\fR, \fBstruct t_bind *\fR\fIret\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces that evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fRheader file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function associates a protocol address with the transport endpoint +specified by \fIfd\fR and activates that transport endpoint. In connection +mode, the transport provider may begin enqueuing incoming connect indications, +or servicing a connection request on the transport endpoint. In +connectionless-mode, the transport user may send or receive data units through +the transport endpoint. +.sp +.LP +The \fIreq\fR and \fIret\fR arguments point to a \fBt_bind\fR structure +containing the following members: +.sp +.in +2 +.nf +struct netbuf addr; +unsigned qlen; +.fi +.in -2 + +.sp +.LP +The \fIaddr\fR field of the \fBt_bind\fR structure specifies a protocol +address, and the \fIqlen\fR field is used to indicate the maximum number of +outstanding connection indications. +.sp +.LP +The parameter \fIreq\fR is used to request that an address, represented by the +\fBnetbuf\fR structure, be bound to the given transport endpoint. The parameter +\fIlen\fR specifies the number of bytes in the address, and \fIbuf\fR points to +the address buffer. The parameter \fImaxlen\fR has no meaning for the \fIreq\fR +argument. On return, \fIret\fR contains an encoding for the address that the +transport provider actually bound to the transport endpoint; if an address was +specified in \fIreq\fR, this will be an encoding of the same address. In +\fIret\fR, the user specifies \fImaxlen,\fR which is the maximum size of the +address buffer, and \fIbuf\fR which points to the buffer where the address is +to be placed. On return, \fIlen\fR specifies the number of bytes in the bound +address, and \fIbuf\fR points to the bound address. If \fImaxlen\fR equals +zero, no address is returned. If \fImaxlen\fR is greater than zero and less +than the length of the address, \fBt_bind()\fR fails with \fBt_errno\fR set to +\fBTBUFOVFLW\fR. +.sp +.LP +If the requested address is not available, \fBt_bind()\fR will return -1 with +\fBt_errno\fR set as appropriate. If no address is specified in \fIreq\fR (the +\fIlen\fR field of \fIaddr\fR in \fIreq\fR is zero or \fIreq\fR is +\fBNULL),\fR the transport provider will assign an appropriate address to be +bound, and will return that address in the \fIaddr\fR field of \fIret\fR. If +the transport provider could not allocate an address, \fBt_bind()\fR will fail +with \fBt_errno\fR set to \fBTNOADDR\fR. +.sp +.LP +The parameter \fIreq\fR may be a null pointer if the user does not wish to +specify an address to be bound. Here, the value of \fIqlen\fR is assumed to be +zero, and the transport provider will assign an address to the transport +endpoint. Similarly, \fIret\fR may be a null pointer if the user does not care +what address was bound by the provider and is not interested in the negotiated +value of \fIqlen\fR. It is valid to set \fIreq\fR and \fIret\fR to the null +pointer for the same call, in which case the provider chooses the address to +bind to the transport endpoint and does not return that information to the +user. +.sp +.LP +The \fIqlen\fR field has meaning only when initializing a connection-mode +service. It specifies the number of outstanding connection indications that the +transport provider should support for the given transport endpoint. An +outstanding connection indication is one that has been passed to the transport +user by the transport provider but which has not been accepted or rejected. A +value of \fIqlen\fR greater than zero is only meaningful when issued by a +passive transport user that expects other users to call it. The value of +\fIqlen\fR will be negotiated by the transport provider and may be changed if +the transport provider cannot support the specified number of outstanding +connection indications. However, this value of \fIqlen\fR will never be +negotiated from a requested value greater than zero to zero. This is a +requirement on transport providers; see \fBWARNINGS\fR below. On return, the +\fIqlen\fR field in \fIret\fR will contain the negotiated value. +.sp +.LP +If \fIfd\fR refers to a connection-mode service, this function allows more than +one transport endpoint to be bound to the same protocol address. but it is not +possible to bind more than one protocol address to the same transport endpoint. +However, the transport provider must also support this capability. If a user +binds more than one transport endpoint to the same protocol address, only one +endpoint can be used to listen for connection indications associated with that +protocol address. In other words, only one \fBt_bind()\fR for a given protocol +address may specify a value of \fIqlen\fR greater than zero. In this way, the +transport provider can identify which transport endpoint should be notified of +an incoming connection indication. If a user attempts to bind a protocol +address to a second transport endpoint with a value of \fIqlen\fR greater than +zero, \fBt_bind()\fR will return -1 and set \fBt_errno\fR to \fBTADDRBUSY\fR. +When a user accepts a connection on the transport endpoint that is being used +as the listening endpoint, the bound protocol address will be found to be busy +for the duration of the connection, until a \fBt_unbind\fR(3NSL) or +\fBt_close\fR(3NSL) call has been issued. No other transport endpoints may be +bound for listening on that same protocol address while that initial listening +endpoint is active (in the data transfer phase or in the \fBT_IDLE\fR state). +This will prevent more than one transport endpoint bound to the same protocol +address from accepting connection indications. +.sp +.LP +If \fIfd\fR refers to connectionless mode service, this function allows for +more than one transport endpoint to be associated with a protocol address, +where the underlying transport provider supports this capability (often in +conjunction with value of a protocol-specific option). If a user attempts to +bind a second transport endpoint to an already bound protocol address when such +capability is not supported for a transport provider, \fBt_bind()\fR will +return -1 and set \fBt_errno\fR to \fBTADDRBUSY\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of 0 is returned. Otherwise, a value of +-1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_UNBND\fR +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTACCES\fR\fR +.ad +.RS 13n +.rt +The user does not have permission to use the specified address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTADDRBUSY\fR\fR +.ad +.RS 13n +.rt +The requested address is in use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADADDR\fR\fR +.ad +.RS 13n +.rt +The specified protocol address was in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 13n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 13n +.rt +The number of bytes allowed for an incoming argument \fI(maxlen)\fR is greater +than 0 but not sufficient to store the value of that argument. The provider's +state will change to \fBT_IDLE\fR and the information to be returned in +\fIret\fR will be discarded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 13n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOADDR\fR\fR +.ad +.RS 13n +.rt +The transport provider could not allocate an address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 13n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 13n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.LP +\fB#include\fR \fB<tiuser.h>\fR +.SS "Address Bound" +.sp +.LP +The user can compare the addresses in \fIreq\fR and \fIret\fR to determine +whether the transport provider bound the transport endpoint to a different +address than that requested. +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values \fBTPROTO\fR and \fBTADDRBUSY\fR can be set by the +\fBXTI\fR interface but cannot be set by the \fBTLI\fR interface. +.sp +.LP +A \fBt_errno\fR value that this routine can return under different +circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW\fR. It can be +returned even when the \fBmaxlen\fR field of the corresponding buffer has been +set to zero. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_accept\fR(3NSL), \fBt_alloc\fR(3NSL), \fBt_close\fR(3NSL), +\fBt_connect\fR(3NSL), \fBt_unbind\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +The requirement that the value of \fIqlen\fR never be negotiated from a +requested value greater than zero to zero implies that transport providers, +rather than the XTI implementation itself, accept this restriction. +.sp +.LP +An implementation need not allow an application explicitly to bind more than +one communications endpoint to a single protocol address, while permitting more +than one connection to be accepted to the same protocol address. That means +that although an attempt to bind a communications endpoint to some address with +\fIqlen=0\fR might be rejected with \fBTADDRBUSY\fR, the user may nevertheless +use this (unbound) endpoint as a responding endpoint in a call to +\fBt_accept\fR(3NSL). To become independent of such implementation differences, +the user should supply unbound responding endpoints to \fBt_accept\fR(3NSL). +.sp +.LP +The local address bound to an endpoint may change as result of a +\fBt_accept\fR(3NSL) or \fBt_connect\fR(3NSL) call. Such changes are not +necessarily reversed when the connection is released. diff --git a/usr/src/man/man3nsl/t_close.3nsl b/usr/src/man/man3nsl/t_close.3nsl new file mode 100644 index 0000000000..182d9906a4 --- /dev/null +++ b/usr/src/man/man3nsl/t_close.3nsl @@ -0,0 +1,156 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_close 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_close \- close a transport endpoint +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_close\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_close()\fR function informs the transport provider that the user is +finished with the transport endpoint specified by \fIfd\fR, and frees any local +library resources associated with the endpoint. In addition, \fBt_close()\fR +closes the file associated with the transport endpoint. +.sp +.LP +The function \fBt_close()\fR should be called from the \fBT_UNBND\fR state. See +\fBt_getstate\fR(3NSL). However, this function does not check state +information, so it may be called from any state to close a transport endpoint. +If this occurs, the local library resources associated with the endpoint will +be freed automatically. In addition, \fBclose\fR(2) will be issued for that +file descriptor; if there are no other descriptors in this process or in +another process which references the communication endpoint, any connection +that may be associated with that endpoint is broken. The connection may be +terminated in an orderly or abortive manner. +.sp +.LP +A \fBt_close()\fR issued on a connection endpoint may cause data previously +sent, or data not yet received, to be lost. It is the responsibility of the +transport user to ensure that data is received by the remote peer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR \fBis\fR returned. Otherwise, +a value of -1 \fBis\fR \fBreturned\fR \fBand\fR \fBt_errno\fR is set to +indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_UNBND\fR +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 11n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 11n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 11n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.LP +\fB#include\fR \fB<tiuser.h>\fR +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR \fR +.ad +.RS 11n +.rt + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBt_getstate\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_unbind\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_connect.3nsl b/usr/src/man/man3nsl/t_connect.3nsl new file mode 100644 index 0000000000..ab5433bd8d --- /dev/null +++ b/usr/src/man/man3nsl/t_connect.3nsl @@ -0,0 +1,351 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_connect 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_connect \- establish a connection with another transport user +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + +\fBint\fR \fBt_connect\fR(\fBint\fR \fIfd\fR, \fBconst struct t_call *\fR\fIsndcall\fR, + \fBstruct t_call *\fR\fIrcvcall\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. This function enables a transport user to request a connection to +the specified destination transport user. +.sp +.LP +This function can only be issued in the \fBT_IDLE\fR state. The parameter +\fIfd\fR identifies the local transport endpoint where communication will be +established, while \fIsndcall\fR and \fIrcvcall\fR point to a \fBt_call\fR +structure which contains the following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +struct netbuf udata; +int sequence; +.fi +.in -2 + +.sp +.LP +The parameter \fIsndcall\fR specifies information needed by the transport +provider to establish a connection and \fIrcvcall\fR specifies information that +is associated with the newly established connection. +.sp +.LP +In \fIsndcall\fR, \fIaddr\fR specifies the protocol address of the destination +transport user, \fIopt\fR presents any protocol-specific information that might +be needed by the transport provider, \fIudata\fR points to optional user data +that may be passed to the destination transport user during connection +establishment, and \fIsequence\fR has no meaning for this function. +.sp +.LP +On return, in \fIrcvcall\fR, \fIaddr\fR contains the protocol address +associated with the responding transport endpoint, \fIopt\fR represents any +protocol-specific information associated with the connection, \fIudata\fR +points to optional user data that may be returned by the destination transport +user during connection establishment, and \fIsequence\fR has no meaning for +this function. +.sp +.LP +The \fIopt\fR argument permits users to define the options that may be passed +to the transport provider. The user may choose not to negotiate protocol +options by setting the \fIlen\fR field of \fIopt\fR to zero. In this case, the +provider uses the option values currently set for the communications endpoint. +.sp +.LP +If used, \fIsndcall\(->opt.buf\fR must point to a buffer with the corresponding +options, and \fIsndcall\(->opt.len\fR must specify its length. The +\fImaxlen\fR and \fIbuf\fR fields of the \fBnetbuf\fR structure pointed by +\fIrcvcall\(->addr\fR and \fIrcvcall\(->opt\fR must be set before the call. +.sp +.LP +The \fIudata\fR argument enables the caller to pass user data to the +destination transport user and receive user data from the destination user +during connection establishment. However, the amount of user data must not +exceed the limits supported by the transport provider as returned in the +\fIconnect\fR field of the \fIinfo\fR argument of \fBt_open\fR(3NSL) or +\fBt_getinfo\fR(3NSL). If the \fIlen\fR of \fIudata\fR is zero in +\fIsndcall\fR, no data will be sent to the destination transport user. +.sp +.LP +On return, the \fIaddr\fR, \fIopt\fR and \fIudata\fR fields of \fIrcvcall\fR +will be updated to reflect values associated with the connection. Thus, the +\fImaxlen\fR field of each argument must be set before issuing this function to +indicate the maximum size of the buffer for each. However, \fImaxlen\fR can be +set to zero, in which case no information to this specific argument is given to +the user on the return from \fBt_connect()\fR. If maxlen is greater than zero +and less than the length of the value, \fBt_connect()\fR fails with +\fBt_errno\fR set to \fBTBUFOVFLW\fR. If \fIrcvcall\fR is set to \fINULL,\fR +no information at all is returned. +.sp +.LP +By default, \fBt_connect()\fR executes in synchronous mode, and will wait for +the destination user's response before returning control to the local user. A +successful return (that is, return value of zero) indicates that the requested +connection has been established. However, if \fBO_NONBLOCK\fR is set by means +of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_connect()\fR executes in +asynchronous mode. In this case, the call will not wait for the remote user's +response, but will return control immediately to the local user and return -1 +with \fBt_errno\fR set to \fBTNODATA\fR to indicate that the connection has not +yet been established. In this way, the function simply initiates the connection +establishment procedure by sending a connection request to the destination +transport user. The \fBt_rcvconnect\fR(3NSL) function is used in conjunction +with \fBt_connect()\fR to determine the status of the requested connection. +.sp +.LP +When a synchronous \fBt_connect()\fR call is interrupted by the arrival of a +signal, the state of the corresponding transport endpoint is \fBT_OUTCON,\fR +allowing a further call to either \fBt_rcvconnect\fR(3NSL), +\fBt_rcvdis\fR(3NSL) or \fBt_snddis\fR(3NSL). When an asynchronous +\fBt_connect()\fR call is interrupted by the arrival of a signal, the state of +the corresponding transport endpoint is \fBT_IDLE.\fR +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTACCES\fR\fR +.ad +.RS 15n +.rt +The user does not have permission to use the specified address or options. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTADDRBUSY\fR\fR +.ad +.RS 15n +.rt +This transport provider does not support multiple connections with the same +local and remote addresses. This error indicates that a connection already +exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADADDR\fR\fR +.ad +.RS 15n +.rt +The specified protocol address was in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +The amount of user data specified was not within the bounds allowed by the +transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADOPT\fR\fR +.ad +.RS 15n +.rt +The specified protocol options were in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for an incoming argument \fI(maxlen)\fR is +greater than 0 but not sufficient to store the value of that argument. If +executed in synchronous mode, the provider's state, as seen by the user, +changes to \fBT_DATAXFER,\fR and the information to be returned in +\fIrcvcall\fR is discarded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, so the function successfully initiated the connection +establishment procedure, but did not wait for a response from the remote user. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBTPROTO\fR and \fBTADDRBUSY\fR \fBt_errno\fR values can be set by the +\fBXTI\fR interface but not by the \fBTLI\fR interface. +.sp +.LP +A \fBt_errno\fR value that this routine can return under different +circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW\fR. It can be +returned even when the \fBmaxlen\fR field of the corresponding buffer has been +set to zero. +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_accept\fR(3NSL), \fBt_alloc\fR(3NSL), +\fBt_getinfo\fR(3NSL), \fBt_listen\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_optmgmt\fR(3NSL), \fBt_rcvconnect\fR(3NSL), \fBt_rcvdis\fR(3NSL), +\fBt_snddis\fR(3NSL), \fBattributes\fR diff --git a/usr/src/man/man3nsl/t_errno.3nsl b/usr/src/man/man3nsl/t_errno.3nsl new file mode 100644 index 0000000000..ed0e1de076 --- /dev/null +++ b/usr/src/man/man3nsl/t_errno.3nsl @@ -0,0 +1,132 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_errno 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_errno \- XTI error return value +.SH SYNOPSIS +.LP +.nf +#include <xti.h> +.fi + +.SH DESCRIPTION +.sp +.LP +This error return value is part of the XTI interfaces that evolved from the TLI +interfaces. XTI represents the future evolution of these interfaces. However, +TLI interfaces are supported for compatibility. When using a TLI interface that +has the same name as an XTI interfaces, a different headerfile, +<\fBtiuser.h\fR>, must be used. Refer the the TLI COMPATIBILITY section for a +description of differences between the two interfaces. +.sp +.LP +\fBt_errno\fR is used by XTI functions to return error values. +.sp +.LP +XTI functions provide an error number in \fBt_errno\fR which has type +\fIint\fR and is defined in \fB<xti.h>\fR\&. The value of \fBt_errno\fR will +be defined only after a call to a XTI function for which it is explicitly +stated to be set and until it is changed by the next XTI function call. The +value of \fBt_errno\fR should only be examined when it is indicated to be +valid by a function's return value. Programs should obtain the definition of +\fBt_errno\fR by the inclusion of \fB<xti.h>\fR\&. The practice of defining +\fBt_errno\fR in program as \fBextern\fR \fBint\fR \fBt_errno\fR is +obsolescent. No XTI function sets \fBt_errno\fR to 0 to indicate an error. +.sp +.LP +It is unspecified whether \fBt_errno\fR is a macro or an identifier with +external linkage. It represents a modifiable \fBlvalue\fR of type \fIint\fR. +If a macro definition is suppressed in order to access an actual object or a +program defines an identifier with name \fIt_errno\fR, the behavior is +undefined. +.sp +.LP +The symbolic values stored in \fBt_errno\fR by an XTI function are defined in +the \fBERRORS\fR sections in all relevant XTI function definition pages. +.SH TLI COMPATIBILITY +.sp +.LP +\fBt_errno\fR is also used by TLI functions to return error values. +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, <\fBxti.h\fR>. \fBTLI\fR +interfaces should \fInot\fR use this header. They should use the header: +.br +.in +2 +\fB#include <tiuser.h>\fR +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface but cannot +be set by the \fBTLI\fR interface are: +.br +.in +2 +\fBTNOSTRUCTYPE\fR +.in -2 +.br +.in +2 +\fBTBADNAME\fR +.in -2 +.br +.in +2 +\fBTBADQLEN\fR +.in -2 +.br +.in +2 +\fBTADDRBUSY\fR +.in -2 +.br +.in +2 +\fBTINDOUT\fR +.in -2 +.br +.in +2 +\fBTPROVMISMATCH\fR +.in -2 +.br +.in +2 +\fBTRESADDR\fR +.in -2 +.br +.in +2 +\fBTQFULL\fR +.in -2 +.br +.in +2 +\fBTPROTO\fR +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_error.3nsl b/usr/src/man/man3nsl/t_error.3nsl new file mode 100644 index 0000000000..5cbfe4f06a --- /dev/null +++ b/usr/src/man/man3nsl/t_error.3nsl @@ -0,0 +1,148 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd., All Rights Reserved. Portions Copyright 1989 AT&T. Portions Copyright (c) 1998, Sun Microsystems, Inc. , All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_error 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_error \- produce error message +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_error\fR(\fBconst char *\fR\fIerrmsg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_error()\fR function produces a message on the standard error output +which describes the last error encountered during a call to a transport +function. The argument string \fIerrmsg\fR is a user-supplied error message +that gives context to the error. +.sp +.LP +The error message is written as follows: first (if \fIerrmsg\fR is not a null +pointer and the character pointed to be \fIerrmsg\fR is not the null character) +the string pointed to by \fIerrmsg\fR followed by a colon and a space; then a +standard error message string for the current error defined in \fBt_errno\fR. +If \fBt_errno\fR has a value different from \fBTSYSERR\fR, the standard error +message string is followed by a newline character. If, however, \fBt_errno\fR +is equal to \fBTSYSERR\fR, the \fBt_errno\fR string is followed by the standard +error message string for the current error defined in \fBerrno\fR followed by a +newline. +.sp +.LP +The language for error message strings written by \fBt_error()\fR is that of +the current locale. If it is English, the error message string describing the +value in \fBt_errno\fR may be derived from the comments following the +\fBt_errno\fR codes defined in \fBxti.h\fR. The contents of the error message +strings describing the value in \fBerrno\fR are the same as those returned by +the \fBstrerror\fR(3C) function with an argument of \fBerrno\fR. +.sp +.LP +The error number, \fBt_errno\fR, is only set when an error occurs and it is not +cleared on successful calls. +.SH EXAMPLES +.sp +.LP +If a \fBt_connect\fR(3NSL) function fails on transport endpoint \fIfd2\fR +because a bad address was given, the following call might follow the failure: +.sp +.in +2 +.nf +t_error("t_connect failed on fd2"); +.fi +.in -2 + +.sp +.LP +The diagnostic message to be printed would look like: +.sp +.in +2 +.nf +t_connect failed on fd2: incorrect addr format +.fi +.in -2 + +.sp +.LP +where \fIincorrect addr format\fR identifies the specific error that occurred, +and \fIt_connect failed on fd2\fR tells the user which function failed on which +transport endpoint. +.SH RETURN VALUES +.sp +.LP +Upon completion, a value of \fB0\fR is returned. +.SH VALID STATES +.sp +.LP +All - apart from \fBT_UNINIT\fR +.SH ERRORS +.sp +.LP +No errors are defined for the \fBt_error()\fR function. +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.sp +.LP +\fBTPROTO\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_errno\fR(3NSL)\fBstrerror\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_free.3nsl b/usr/src/man/man3nsl/t_free.3nsl new file mode 100644 index 0000000000..96302cdd01 --- /dev/null +++ b/usr/src/man/man3nsl/t_free.3nsl @@ -0,0 +1,176 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_free 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_free \- free a library structure +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_free\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIstruct_type\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_free()\fR function frees memory previously allocated by +\fBt_alloc\fR(3NSL). This function will free memory for the specified +structure, and will also free memory for buffers referenced by the structure. +.sp +.LP +The argument \fIptr\fR points to one of the seven structure types described for +\fBt_alloc\fR(3NSL), and \fIstruct_type\fR identifies the type of that +structure which must be one of the following: +.sp +.in +2 +.nf +T_BIND struct t_bind +T_CALL struct t_call +T_OPTMGMT struct t_optmgmt +T_DIS struct t_discon +T_UNITDATA struct t_unitdata +T_UDERROR struct t_uderr +T_INFO struct t_info +.fi +.in -2 + +.sp +.LP +where each of these structures is used as an argument to one or more transport +functions. +.sp +.LP +The function \fBt_free()\fR will check the \fIaddr\fR, \fIopt\fR and +\fIudata\fR fields of the given structure, as appropriate, and free the buffers +pointed to by the \fIbuf\fR field of the \fBnetbuf\fR structure. If \fIbuf\fR +is a null pointer, \fBt_free()\fR will not attempt to free memory. After all +buffers are freed, \fBt_free()\fR will free the memory associated with the +structure pointed to by \fIptr\fR. +.sp +.LP +Undefined results will occur if \fIptr\fR or any of the \fIbuf\fR pointers +points to a block of memory that was not previously allocated by +\fBt_alloc\fR(3NSL). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to the following: +.sp +.ne 2 +.mk +.na +\fB\fBTNOSTRUCTYPE\fR\fR +.ad +.RS 16n +.rt +Unsupported \fIstruct_type\fR requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 16n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fI(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 16n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR \fR +.ad +.RS 11n +.rt + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_alloc\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_getinfo.3nsl b/usr/src/man/man3nsl/t_getinfo.3nsl new file mode 100644 index 0000000000..1e61e28e11 --- /dev/null +++ b/usr/src/man/man3nsl/t_getinfo.3nsl @@ -0,0 +1,356 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_getinfo 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_getinfo \- get protocol-specific service information +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_getinfo\fR(\fBint\fR \fIfd\fR, \fBstruct t_info *\fR\fIinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function returns the current characteristics of the underlying transport +protocol and/or transport connection associated with file descriptor \fIfd\fR. +The \fIinfo\fR pointer is used to return the same information returned by +\fBt_open\fR(3NSL), although not necessarily precisely the same values. This +function enables a transport user to access this information during any phase +of communication. +.sp +.LP +This argument points to a \fBt_info\fR structure which contains the following +members: +.sp +.in +2 +.nf +t_scalar_t addr; /*max size in octets of the transport protocol address*/ +t_scalar_t options; /*max number of bytes of protocol-specific options */ +t_scalar_t tsdu; /*max size in octets of a transport service data unit */ +t_scalar_t etsdu; /*max size in octets of an expedited transport service*/ + /*data unit (ETSDU) */ +t_scalar_t connect; /*max number of octets allowed on connection */ + /*establishment functions */ +t_scalar_t discon; /*max number of octets of data allowed on t_snddis() */ + /*and t_rcvdis() functions */ +t_scalar_t servtype; /*service type supported by the transport provider */ +t_scalar_t flags; /*other info about the transport provider */ +.fi +.in -2 + +.sp +.LP +The values of the fields have the following meanings: +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 12n +.rt +A value greater than zero indicates the maximum size of a transport protocol +address and a value of \fBT_INVALID\fR (-2) specifies that the transport +provider does not provide user access to transport protocol addresses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoptions\fR\fR +.ad +.RS 12n +.rt +A value greater than zero indicates the maximum number of bytes of +protocol-specific options supported by the provider, and a value of +\fBT_INVALID\fR (-2) specifies that the transport provider does not support +user-settable options. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItsdu\fR\fR +.ad +.RS 12n +.rt +A value greater than zero specifies the maximum size in octets of a transport +service data unit (TSDU); a value of \fBT_NULL\fR (zero) specifies that the +transport provider does not support the concept of TSDU, although it does +support the sending of a datastream with no logical boundaries preserved across +a connection; a value of \fBT_INFINITE\fR (-1) specifies that there is no +limit on the size in octets of a TSDU; and a value of \fBT_INVALID\fR (-2) +specifies that the transfer of normal data is not supported by the transport +provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIetsdu\fR\fR +.ad +.RS 12n +.rt +A value greater than zero specifies the maximum size in octets of an expedited +transport service data unit (ETSDU); a value of \fBT_NULL\fR (zero) specifies +that the transport provider does not support the concept of ETSDU, although it +does support the sending of an expedited data stream with no logical boundaries +preserved across a connection; a value of \fBT_INFINITE\fR (-1) specifies that +there is no limit on the size (in octets) of an ETSDU; and a value of +\fBT_INVALID\fR (-2) specifies that the transfer of expedited data is not +supported by the transport provider. Note that the semantics of expedited data +may be quite different for different transport providers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconnect\fR\fR +.ad +.RS 12n +.rt +A value greater than zero specifies the maximum number of octets that may be +associated with connection establishment functions and a value of +\fBT_INVALID\fR (-2) specifies that the transport provider does not allow data +to be sent with connection establishment functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdiscon\fR\fR +.ad +.RS 12n +.rt +If the \fBT_ORDRELDATA\fR bit in flags is clear, a value greater than zero +specifies the maximum number of octets that may be associated with the +\fBt_snddis\fR(3NSL) and \fBt_rcvdis\fR(3NSL) functions, and a value of +\fBT_INVALID\fR (-2) specifies that the transport provider does not allow data +to be sent with the abortive release functions. If the \fBT_ORDRELDATA\fR bit +is set in flags, a value greater than zero specifies the maximum number of +octets that may be associated with the \fBt_sndreldata()\fR, +\fBt_rcvreldata()\fR, \fBt_snddis\fR(3NSL) and \fBt_rcvdis\fR(3NSL) functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIservtype\fR\fR +.ad +.RS 12n +.rt +This field specifies the service type supported by the transport provider, as +described below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +This is a bit field used to specify other information about the communications +provider. If the \fBT_ORDRELDATA\fR bit is set, the communications provider +supports sending user data with an orderly release. If the \fBT_SENDZERO\fR +bit is set in flags, this indicates that the underlying transport provider +supports the sending of zero-length TSDUs. +.RE + +.sp +.LP +If a transport user is concerned with protocol independence, the above sizes +may be accessed to determine how large the buffers must be to hold each piece +of information. Alternatively, the \fBt_alloc\fR(3NSL) function may be used to +allocate these buffers. An error will result if a transport user exceeds the +allowed data size on any function. The value of each field may change as a +result of protocol option negotiation during connection establishment (the +\fBt_optmgmt\fR(3NSL) call has no effect on the values returned by +\fBt_getinfo()\fR\|). These values will only change from the values presented +to \fBt_open\fR(3NSL) after the endpoint enters the \fBT_DATAXFER\fR state. +.sp +.LP +The \fIservtype\fR field of \fIinfo\fR specifies one of the following values on +return: +.sp +.ne 2 +.mk +.na +\fB\fBT_COTS\fR \fR +.ad +.RS 15n +.rt +The transport provider supports a connection-mode service but does not support +the optional orderly release facility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_COTS_ORD\fR \fR +.ad +.RS 15n +.rt +The transport provider supports a connection-mode service with the optional +orderly release facility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_CLTS\fR \fR +.ad +.RS 15n +.rt +The transport provider supports a connectionless-mode service. For this service +type, \fBt_open\fR(3NSL) will return \fBT_INVALID\fR (-1) for \fIetsdu\fR, +\fIconnect\fR and \fIdiscon\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 11n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 11n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 11n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value \fBTPROTO\fR can be set by the \fBXTI\fR interface but +not by the \fBTLI\fR interface. +.SS "The t_info Structure" +.sp +.LP +For \fBTLI\fR , the \fBt_info\fR structure referenced by \fIinfo\fR lacks the +following structure member: +.sp +.in +2 +.nf +t_scalar_t flags; /* other info about the transport provider */ +.fi +.in -2 + +.sp +.LP +This member was added to \fBstruct\fR \fBt_info\fR in the \fBXTI\fR interfaces. +.sp +.LP +When a value of -1 is observed as the return value in various \fBt_info\fR +structure members, it signifies that the transport provider can handle an +infinite length buffer for a corresponding attribute, such as address data, +option data, \fBTSDU\fR (octet size), \fBETSDU\fR (octet size), connection +data, and disconnection data. The corresponding structure members are +\fBaddr\fR, \fBoptions\fR, \fBtsdu\fR, \fBestdu\fR, \fBconnect\fR, and +\fBdiscon\fR, respectively. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_alloc\fR(3NSL), \fBt_open\fR(3NSL), \fBt_optmgmt\fR(3NSL), +\fBt_rcvdis\fR(3NSL), \fBt_snddis\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_getprotaddr.3nsl b/usr/src/man/man3nsl/t_getprotaddr.3nsl new file mode 100644 index 0000000000..fa015e66f1 --- /dev/null +++ b/usr/src/man/man3nsl/t_getprotaddr.3nsl @@ -0,0 +1,134 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_getprotaddr 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_getprotaddr \- get the protocol addresses +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + +\fBint\fR \fBt_getprotaddr\fR(\fBint\fR \fIfd\fR, \fBstruct t_bind *\fR\fIboundaddr\fR, + \fBstruct t_bind *\fR\fIpeeraddr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_getprotaddr()\fR function returns local and remote protocol addresses +currently associated with the transport endpoint specified by \fIfd\fR. In +\fIboundaddr\fR and \fIpeeraddr\fR the user specifies \fImaxlen\fR, which is +the maximum size (in bytes) of the address buffer, and \fIbuf\fR which points +to the buffer where the address is to be placed. On return, the \fIbuf\fR field +of \fIboundaddr\fR points to the address, if any, currently bound to \fIfd\fR, +and the \fIlen\fR field specifies the length of the address. If the transport +endpoint is in the \fBT_UNBND\fR state, zero is returned in the \fIlen\fR field +of \fIboundaddr\fR. The \fIbuf\fR field of \fIpeeraddr\fR points to the +address, if any, currently connected to \fIfd\fR, and the \fIlen\fR field +specifies the length of the address. If the transport endpoint is not in the +\fBT_DATAXFER,\fR \fBT_INREL,\fR \fBT_OUTCON\fR or \fBT_OUTREL\fR states, zero +is returned in the \fIlen\fR field of \fIpeeraddr\fR. If the \fImaxlen\fR +field of \fIboundaddr\fR or \fIpeeraddr\fR is set to zero, no address is +returned. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate the error. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 13n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 13n +.rt +The number of bytes allocated for an incoming argument (\fImaxlen)\fR is +greater than \fB0\fR but not sufficient to store the value of that argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 13n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 13n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_bind\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_getstate.3nsl b/usr/src/man/man3nsl/t_getstate.3nsl new file mode 100644 index 0000000000..e195e90337 --- /dev/null +++ b/usr/src/man/man3nsl/t_getstate.3nsl @@ -0,0 +1,220 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_getstate 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_getstate \- get the current state +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_getstate\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_getstate()\fR function returns the current state of the provider +associated with the transport endpoint specified by \fIfd\fR. +.SH RETURN VALUES +.sp +.LP +State is returned upon successful completion. Otherwise, a value of -1 is +returned and \fBt_errno\fR is set to indicate an error. The current state is +one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBT_UNBND\fR \fR +.ad +.RS 15n +.rt +Unbound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_IDLE\fR \fR +.ad +.RS 15n +.rt +Idle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OUTCON\fR \fR +.ad +.RS 15n +.rt +Outgoing connection pending. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_INCON\fR \fR +.ad +.RS 15n +.rt +Incoming connection pending. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_DATAXFER\fR \fR +.ad +.RS 15n +.rt +Data transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OUTREL\fR \fR +.ad +.RS 15n +.rt +Outgoing direction orderly release sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_INREL\fR \fR +.ad +.RS 15n +.rt +Incoming direction orderly release received. +.RE + +.sp +.LP +If the provider is undergoing a state transition when \fBt_getstate()\fR is +called, the function will fail. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 14n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 14n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSTATECHNG\fR\fR +.ad +.RS 14n +.rt +The transport provider is undergoing a transient state change. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 14n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.sp +.LP +\fBTPROTO\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_open\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_listen.3nsl b/usr/src/man/man3nsl/t_listen.3nsl new file mode 100644 index 0000000000..813c8c86f4 --- /dev/null +++ b/usr/src/man/man3nsl/t_listen.3nsl @@ -0,0 +1,276 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_listen 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_listen \- listen for a connection indication +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_listen\fR(\fBint\fR \fIfd\fR, \fBstruct t_call *\fR\fIcall\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function listens for a connection indication from a calling transport +user. The argument \fIfd\fR identifies the local transport endpoint where +connection indications arrive, and on return, \fIcall\fR contains information +describing the connection indication. The parameter \fIcall\fR points to a +\fBt_call\fR structure which contains the following members: +.sp +.in +2 +.nf +\fBstruct netbuf addr; +struct netbuf opt; +struct netbuf udata; +int sequence;\fR +.fi +.in -2 + +.sp +.LP +In \fIcall\fR, \fIaddr\fR returns the protocol address of the calling transport +user. This address is in a format usable in future calls to +\fBt_connect\fR(3NSL). Note, however that \fBt_connect\fR(3NSL) may fail for +other reasons, for example \fBTADDRBUSY\fR. \fIopt\fR returns options +associated with the connection indication, \fIudata\fR returns any user data +sent by the caller on the connection request, and \fIsequence\fR is a number +that uniquely identifies the returned connection indication. The value of +\fIsequence\fR enables the user to listen for multiple connection indications +before responding to any of them. +.sp +.LP +Since this function returns values for the \fIaddr\fR, \fIopt\fR and +\fIudata\fR fields of \fIcall\fR, the \fImaxlen\fR field of each must be set +before issuing the \fBt_listen()\fR to indicate the maximum size of the buffer +for each. If the \fImaxlen\fR field of \fIcall\(->addr\fR, \fIcall\(->opt\fR +or \fIcall\(->udata\fR is set to zero, no information is returned for this +parameter. +.sp +.LP +By default, \fBt_listen()\fR executes in synchronous mode and waits for a +connection indication to arrive before returning to the user. However, if +\fBO_NONBLOCK\fR is set via \fBt_open\fR(3NSL) or \fBfcntl\fR(2), +\fBt_listen()\fR executes asynchronously, reducing to a poll for existing +connection indications. If none are available, it returns -1 and sets +\fBt_errno\fR to \fBTNODATA\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of 0 is returned. Otherwise, a value of +\(mi1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR, \fBT_INCON\fR +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADQLEN\fR\fR +.ad +.RS 15n +.rt +The argument \fIqlen\fR of the endpoint referenced by \fIfd\fR is zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for an incoming argument \fI(maxlen)\fR is +greater than 0 but not sufficient to store the value of that argument. The +provider's state, as seen by the user, changes to \fBT_INCON,\fR and the +connection indication information to be returned in \fIcall\fR is discarded. +The value of \fIsequence\fR returned can be used to do a \fBt_snddis\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but no connection indications had been queued. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTQFULL\fR\fR +.ad +.RS 15n +.rt +The maximum number of outstanding connection indications has been reached for +the endpoint referenced by \fIfd\fR. Note that a subsequent call to +\fBt_listen()\fR may block until another incoming connection indication is +available. This can only occur if at least one of the outstanding connection +indications becomes no longer outstanding, for example through a call to +\fBt_accept\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values \fBTPROT0,\fR \fBTBADQLEN,\fR and \fBTQFULL\fR can be +set by the \fBXTI\fR interface but not by the \fBTLI\fR interface. +.sp +.LP +A \fBt_errno\fR value that this routine can return under different +circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW\fR. It can be +returned even when the \fBmaxlen\fR field of the corresponding buffer has been +set to zero. +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_accept\fR(3NSL), \fBt_alloc\fR(3NSL), \fBt_bind\fR(3NSL), +\fBt_connect\fR(3NSL), \fBt_open\fR(3NSL), \fBt_optmgmt\fR(3NSL), +\fBt_rcvconnect\fR(3NSL), \fBt_snddis\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +Some transport providers do not differentiate between a connection indication +and the connection itself. If this is the case, a successful return of +\fBt_listen()\fR indicates an existing connection. diff --git a/usr/src/man/man3nsl/t_look.3nsl b/usr/src/man/man3nsl/t_look.3nsl new file mode 100644 index 0000000000..8f5dc890f7 --- /dev/null +++ b/usr/src/man/man3nsl/t_look.3nsl @@ -0,0 +1,259 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_look 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_look \- look at the current event on a transport endpoint +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_look\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function returns the current event on the transport endpoint specified by +\fIfd\fR. This function enables a transport provider to notify a transport user +of an asynchronous event when the user is calling functions in synchronous +mode. Certain events require immediate notification of the user and are +indicated by a specific error, \fBTLOOK\fR, on the current or next function to +be executed. +.sp +.LP +This function also enables a transport user to poll a transport endpoint +periodically for asynchronous events. +.SH RETURN VALUES +.sp +.LP +Upon success, \fBt_look()\fR returns a value that indicates which of the +allowable events has occurred, or returns zero if no event exists. One of the +following events is returned: +.sp +.ne 2 +.mk +.na +\fB\fBT_LISTEN\fR \fR +.ad +.RS 17n +.rt +Connection indication received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_CONNECT\fR \fR +.ad +.RS 17n +.rt +Connect confirmation received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_DATA\fR \fR +.ad +.RS 17n +.rt +Normal data received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_EXDATA\fR \fR +.ad +.RS 17n +.rt +Expedited data received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_DISCONNECT\fR \fR +.ad +.RS 17n +.rt +Disconnection received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_UDERR\fR \fR +.ad +.RS 17n +.rt +Datagram error indication. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_ORDREL\fR \fR +.ad +.RS 17n +.rt +Orderly release indication. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_GODATA\fR \fR +.ad +.RS 17n +.rt +Flow control restrictions on normal data flow that led to a \fBTFLOW\fR error +have been lifted. Normal data may be sent again. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_GOEXDATA\fR \fR +.ad +.RS 17n +.rt +Flow control restrictions on expedited data flow that led to a \fBTFLOW\fR +error have been lifted. Expedited data may be sent again. +.RE + +.sp +.LP +On failure, -1 is returned and \fBt_errno\fR is set to indicate the error. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 11n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 11n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 11n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Return Values" +.sp +.LP +The return values that are defined by the \fBXTI\fR interface and cannot be +returned by the \fBTLI\fR interface are: +.br +.in +2 +\fBT_GODATA\fR +.in -2 +.br +.in +2 +\fBT_GOEXDATA\fR +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_open\fR(3NSL), \fBt_snd\fR(3NSL), \fBt_sndudata\fR(3NSL), +\fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_open.3nsl b/usr/src/man/man3nsl/t_open.3nsl new file mode 100644 index 0000000000..82d9a0d198 --- /dev/null +++ b/usr/src/man/man3nsl/t_open.3nsl @@ -0,0 +1,381 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_open 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_open \- establish a transport endpoint +.SH SYNOPSIS +.LP +.nf +#include <xti.h> +#include <fcntl.h> + + + + +\fBint\fR \fBt_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR, \fBstruct t_info *\fR\fIinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_open()\fR function must be called as the first step in the +initialization of a transport endpoint. This function establishes a transport +endpoint by supplying a transport provider identifier that indicates a +particular transport provider, that is, transport protocol, and returning a +file descriptor that identifies that endpoint. +.sp +.LP +The argument \fIname\fR points to a transport provider identifier and +\fIoflag\fR identifies any open flags, as in \fBopen\fR(2). The argument +\fIoflag\fR is constructed from \fBO_RDWR\fR optionally bitwise +inclusive-OR'ed with \fBO_NONBLOCK.\fR These flags are defined by the header +\fB<fcntl.h>\fR\&. The file descriptor returned by \fBt_open()\fR will be used +by all subsequent functions to identify the particular local transport +endpoint. +.sp +.LP +This function also returns various default characteristics of the underlying +transport protocol by setting fields in the \fBt_info\fR structure. This +argument points to a \fBt_info\fR which contains the following members: +.sp +.in +2 +.nf +t_scalar_t addr; /* max size of the transport protocol address */ +t_scalar_t options; /* max number of bytes of */ + /* protocol-specific options */ +t_scalar_t tsdu; /* max size of a transport service data */ + /* unit (TSDU) */ +t_scalar_t etsdu; /* max size of an expedited transport */ + /* service data unit (ETSDU) */ +t_scalar_t connect; /* max amount of data allowed on */ + /* connection establishment functions */ +t_scalar_t discon; /* max amount of data allowed on */ + /* t_snddis() and t_rcvdis() functions */ +t_scalar_t servtype; /* service type supported by the */ + /* transport provider */ +t_scalar_t flags; /* other info about the transport provider */ +.fi +.in -2 + +.sp +.LP +The values of the fields have the following meanings: +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 12n +.rt +A value greater than zero (\fBT_NULL\fR) indicates the maximum size of a +transport protocol address and a value of -2 (\fBT_INVALID\fR) specifies that +the transport provider does not provide user access to transport protocol +addresses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoptions\fR\fR +.ad +.RS 12n +.rt +A value greater than zero (\fBT_NULL\fR) indicates the maximum number of bytes +of protocol-specific options supported by the provider, and a value of -2 +(\fBT_INVALID\fR) specifies that the transport provider does not support +user-settable options. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItsdu\fR\fR +.ad +.RS 12n +.rt +A value greater than zero (\fBT_NULL\fR specifies the maximum size of a +transport service data unit (TSDU); a value of zero (\fBT_NULL\fR) specifies +that the transport provider does not support the concept of TSDU, although it +does support the sending of a data stream with no logical boundaries preserved +across a connection; a value of -1 (\fBT_INFINITE\fR) specifies that there is +no limit to the size of a TSDU; and a value of -2 (\fBT_INVALID\fR) specifies +that the transfer of normal data is not supported by the transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIetsdu\fR\fR +.ad +.RS 12n +.rt +A value greater than zero (\fBT_NULL\fR) specifies the maximum size of an +expedited transport service data unit (ETSDU); a value of zero (\fBT_NULL\fR) +specifies that the transport provider does not support the concept of ETSDU, +although it does support the sending of an expedited data stream with no +logical boundaries preserved across a connection; a value of -1 +(\fBT_INFINITE\fR) specifies that there is no limit on the size of an ETSDU; +and a value of -2 (\fBT_INVALID\fR) specifies that the transfer of expedited +data is not supported by the transport provider. Note that the semantics of +expedited data may be quite different for different transport providers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconnect\fR\fR +.ad +.RS 12n +.rt +A value greater than zero (\fBT_NULL\fR) specifies the maximum amount of data +that may be associated with connection establishment functions, and a value of +-2 (\fBT_INVALID\fR) specifies that the transport provider does not allow data +to be sent with connection establishment functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdiscon\fR\fR +.ad +.RS 12n +.rt +If the \fBT_ORDRELDATA\fR bit in flags is clear, a value greater than zero +(\fBT_NULL\fR) specifies the maximum amount of data that may be associated with +the \fBt_snddis\fR(3NSL) and \fBt_rcvdis\fR(3NSL) functions, and a value of -2 +(\fBT_INVALID\fR) specifies that the transport provider does not allow data to +be sent with the abortive release functions. If the \fBT_ORDRELDATA\fR bit is +set in flags, a value greater than zero (\fBT_NULL\fR) specifies the maximum +number of octets that may be associated with the \fBt_sndreldata()\fR, +\fBt_rcvreldata()\fR, \fBt_snddis\fR(3NSL) and \fBt_rcvdis\fR(3NSL) functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIservtype\fR\fR +.ad +.RS 12n +.rt +This field specifies the service type supported by the transport provider, as +described below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +This is a bit field used to specify other information about the communications +provider. If the \fBT_ORDRELDATA\fR bit is set, the communications provider +supports user data to be sent with an orderly release. If the \fBT_SENDZERO\fR +bit is set in flags, this indicates the underlying transport provider supports +the sending of zero-length TSDUs. +.RE + +.sp +.LP +If a transport user is concerned with protocol independence, the above sizes +may be accessed to determine how large the buffers must be to hold each piece +of information. Alternatively, the \fBt_alloc\fR(3NSL) function may be used to +allocate these buffers. An error will result if a transport user exceeds the +allowed data size on any function. +.sp +.LP +The \fIservtype\fR field of \fIinfo\fR specifies one of the following values on +return: +.sp +.ne 2 +.mk +.na +\fB\fBT_COTS\fR \fR +.ad +.RS 15n +.rt +The transport provider supports a connection-mode service but does not support +the optional orderly release facility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_COTS_ORD\fR \fR +.ad +.RS 15n +.rt +The transport provider supports a connection-mode service with the optional +orderly release facility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_CLTS\fR \fR +.ad +.RS 15n +.rt +The transport provider supports a connectionless-mode service. For this service +type, \fBt_open()\fR will return -2 (\fBT_INVALID\fR) for \fIetsdu\fR, +\fIconnect\fR and \fIdiscon\fR. +.RE + +.sp +.LP +A single transport endpoint may support only one of the above services at one +time. +.sp +.LP +If \fIinfo\fR is set to a null pointer by the transport user, no protocol +information is returned by \fBt_open()\fR. +.SH RETURN VALUES +.sp +.LP +A valid file descriptor is returned upon successful completion. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_UNINIT\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADFLAG\fR\fR +.ad +.RS 12n +.rt +An invalid flag is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADNAME\fR\fR +.ad +.RS 12n +.rt +Invalid transport provider name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 12n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 12n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the \fBxti.h\fR \fBTLI\fR interfaces should +\fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values \fBTPROTO\fR and \fBTBADNAME\fR can be set by the +\fBXTI\fR interface but cannot be set by the \fBTLI\fR interface. +.SS "Notes" +.sp +.LP +For \fBTLI\fR , the \fBt_info\fR structure referenced by \fIinfo\fR lacks the +following structure member: +.sp +.in +2 +.nf +t_scalar_t flags; /* other info about the transport provider */ +.fi +.in -2 + +.sp +.LP +This member was added to \fBstruct\fR \fBt_info\fR in the \fBXTI\fR interfaces. +.sp +.LP +When a value of -1 is observed as the return value in various \fBt_info\fR +structure members, it signifies that the transport provider can handle an +infinite length buffer for a corresponding attribute, such as address data, +option data, \fBTSDU\fR (octet size), \fBETSDU\fR (octet size), connection +data, and disconnection data. The corresponding structure members are +\fBaddr\fR, \fBoptions\fR, \fBtsdu\fR, \fBestdu\fR, \fBconnect\fR, and +\fBdiscon\fR, respectively. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_optmgmt.3nsl b/usr/src/man/man3nsl/t_optmgmt.3nsl new file mode 100644 index 0000000000..8ca29017fa --- /dev/null +++ b/usr/src/man/man3nsl/t_optmgmt.3nsl @@ -0,0 +1,544 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_optmgmt 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_optmgmt \- manage options for a transport endpoint +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_optmgmt\fR(\fBint\fR \fIfd\fR, \fBconst struct t_optmgmt *\fR\fIreq\fR, \fBstruct t_optmgmt *\fR\fIret\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_optmgmt()\fR function enables a transport user to retrieve, verify or +negotiate protocol options with the transport provider. The argument \fIfd\fR +identifies a transport endpoint. +.sp +.LP +The \fIreq\fR and \fIret\fR arguments point to a \fBt_optmgmt\fR structure +containing the following members: +.sp +.in +2 +.nf +\fBstruct netbuf opt; +t_scalar_t flags;\fR +.fi +.in -2 + +.sp +.LP +The \fIopt\fR field identifies protocol options and the \fIflags\fR field is +used to specify the action to take with those options. +.sp +.LP +The options are represented by a \fBnetbuf\fR structure in a manner similar to +the address in \fBt_bind\fR(3NSL). The argument \fIreq\fR is used to request a +specific action of the provider and to send options to the provider. The +argument \fIlen\fR specifies the number of bytes in the options, \fIbuf\fR +points to the options buffer, and \fImaxlen\fR has no meaning for the \fIreq\fR +argument. The transport provider may return options and flag values to the user +through \fIret\fR. For \fIret\fR, \fImaxlen\fR specifies the maximum size of +the options buffer and \fIbuf\fR points to the buffer where the options are to +be placed. If \fImaxlen\fR in \fIret\fR is set to zero, no options values are +returned. On return, \fIlen\fR specifies the number of bytes of options +returned. The value in \fImaxlen\fR has no meaning for the \fIreq\fR argument, +but must be set in the \fIret\fR argument to specify the maximum number of +bytes the options buffer can hold. +.sp +.LP +Each option in the options buffer is of the form \fBstruct t_opthdr\fR possibly +followed by an option value. +.sp +.LP +The \fIlevel\fR field of \fBstruct t_opthdr\fR identifies the XTI level or a +protocol of the transport provider. The \fIname\fR field identifies the option +within the level, and \fIlen\fR contains its total length; that is, the length +of the option header \fBt_opthdr\fR plus the length of the option value. If +\fBt_optmgmt()\fR is called with the action \fBT_NEGOTIATE\fR set, the +\fIstatus\fR field of the returned options contains information about the +success or failure of a negotiation. +.sp +.LP +Several options can be concatenated. The option user has, however to ensure +that each options header and value part starts at a boundary appropriate for +the architecture\(hyspecific alignment rules. The macros +\fBT_OPT_FIRSTHDR\fR(nbp), \fBT_OPT_NEXTHDR\fR (nbp,tohp), +\fBT_OPT_DATA\fR(tohp) are provided for that purpose. +.sp +.ne 2 +.mk +.na +\fB\fBT_OPT_DATA(nhp)\fR \fR +.ad +.RS 29n +.rt +If argument is a pointer to a \fBt_opthdr\fR structure, this macro returns an +unsigned character pointer to the data associated with the \fBt_opthdr\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OPT_NEXTHDR(nbp,\fR \fBtohp)\fR \fR +.ad +.RS 29n +.rt +If the first argument is a pointer to a netbuf structure associated with an +option buffer and second argument is a pointer to a \fBt_opthdr\fR structure +within that option buffer, this macro returns a pointer to the next +\fBt_opthdr\fR structure or a null pointer if this \fBt_opthdr\fR is the last +\fBt_opthdr\fR in the option buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OPT_FIRSTHDR(tohp)\fR \fR +.ad +.RS 29n +.rt +If the argument is a pointer to a \fBnetbuf\fR structure associated with an +option buffer, this macro returns the pointer to the first \fBt_opthdr\fR +structure in the associated option buffer, or a null pointer if there is no +option buffer associated with this \fBnetbuf\fR or if it is not possible or the +associated option buffer is too small to accommodate even the first aligned +option header. +.sp +\fBT_OPT_FIRSTHDR\fR is useful for finding an appropriately aligned start of +the option buffer. \fBT_OPT_NEXTHDR\fR is useful for moving to the start of the +next appropriately aligned option in the option buffer. Note that +\fBOPT_NEXTHDR\fR is also available for backward compatibility requirements. +\fBT_OPT_DATA\fR is useful for finding the start of the data part in the option +buffer where the contents of its values start on an appropriately aligned +boundary. +.sp +If the transport user specifies several options on input, all options must +address the same level. +.sp +If any option in the options buffer does not indicate the same level as the +first option, or the level specified is unsupported, then the \fBt_optmgmt()\fR +request will fail with \fBTBADOPT\fR. If the error is detected, some options +have possibly been successfully negotiated. The transport user can check the +current status by calling \fBt_optmgmt()\fR with the \fBT_CURRENT\fR flag set. +.sp +The \fIflags\fR field of \fIreq\fR must specify one of the following actions: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_NEGOTIATE\fR \fR +.ad +.RS 29n +.rt +This action enables the transport user to negotiate option values. +.sp +The user specifies the options of interest and their values in the buffer +specified by \fIreq\(->opt.buf\fR and \fIreq\(->opt.len\fR. The negotiated +option values are returned in the buffer pointed to by \fIret->opt.buf\fR. The +\fIstatus\fR field of each returned option is set to indicate the result of the +negotiation. The value is \fBT_SUCCESS\fR if the proposed value was +negotiated, \fBT_PARTSUCCESS\fR if a degraded value was negotiated, +\fBT_FAILURE\fR if the negotiation failed (according to the negotiation rules), +\fBT_NOTSUPPORT\fR if the transport provider does not support this option or +illegally requests negotiation of a privileged option, and \fBT_READONLY\fR if +modification of a read-only option was requested. If the status is +\fBT_SUCCESS,\fR \fBT_FAILURE,\fR \fBT_NOTSUPPORT\fR or \fBT_READONLY,\fR the +returned option value is the same as the one requested on input. +.sp +The overall result of the negotiation is returned in \fIret\(->flags\fR. +.sp +This field contains the worst single result, whereby the rating is done +according to the order \fBT_NOTSUPPORT,\fR \fBT_READONLY,\fR \fBT_FAILURE,\fR +\fBT_PARTSUCCESS,\fR \fBT_SUCCESS.\fR The value \fBT_NOTSUPPORT\fR is the +worst result and \fBT_SUCCESS\fR is the best. +.sp +For each level, the option \fBT_ALLOPT\fR can be requested on input. No value +is given with this option; only the \fBt_opthdr\fR part is specified. This +input requests to negotiate all supported options of this level to their +default values. The result is returned option by option in +\fIret\(->opt.buf\fR. Note that depending on the state of the transport +endpoint, not all requests to negotiate the default value may be successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_CHECK\fR \fR +.ad +.RS 29n +.rt +This action enables the user to verify whether the options specified in +\fIreq\fR are supported by the transport provider.If an option is specified +with no option value (it consists only of a \fBt_opthdr\fR structure), the +option is returned with its \fIstatus\fR field set to \fBT_SUCCESS\fR if it is +supported, \fBT_NOTSUPPORT\fR if it is not or needs additional user +privileges, and \fBT_READONLY\fR if it is read-only (in the current XTI +state). No option value is returned. +.sp +If an option is specified with an option value, the \fIstatus\fR field of the +returned option has the same value, as if the user had tried to negotiate this +value with \fBT_NEGOTIATE.\fR If the status is \fBT_SUCCESS\fR, +\fBT_FAILURE\fR, \fBT_NOTSUPPORT\fR or \fBT_READONLY\fR, the returned option +value is the same as the one requested on input. +.sp +The overall result of the option checks is returned in \fIret\(->flags\fR. This +field contains the worst single result of the option checks, whereby the rating +is the same as for \fBT_NEGOTIATE\fR . +.sp +Note that no negotiation takes place. All currently effective option values +remain unchanged. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_DEFAULT\fR \fR +.ad +.RS 29n +.rt +This action enables the transport user to retrieve the default option values. +The user specifies the options of interest in \fIreq\(->opt.buf\fR. The option +values are irrelevant and will be ignored; it is sufficient to specify the +\fBt_opthdr\fR part of an option only. The default values are then returned in +\fIret\(->opt.buf\fR. +.sp +The \fIstatus\fR field returned is \fBT_NOTSUPPORT\fR if the protocol level +does not support this option or the transport user illegally requested a +privileged option, \fBT_READONLY\fR if the option is read-only, and set to +\fBT_SUCCESS\fR in all other cases. The overall result of the request is +returned in \fIret\(->flags\fR. This field contains the worst single result, +whereby the rating is the same as for \fBT_NEGOTIATE.\fR +.sp +For each level, the option \fBT_ALLOPT\fR can be requested on input. All +supported options of this level with their default values are then returned. In +this case, \fIret\(->opt.maxlen\fR must be given at least the value +\fIinfo\(->options\fR before the call. See \fBt_getinfo\fR(3NSL) and +\fBt_open\fR(3NSL). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_CURRENT\fR\fR +.ad +.RS 29n +.rt +This action enables the transport user to retrieve the currently effective +option values. The user specifies the options of interest in +\fIreq\(->opt.buf\fR. The option values are irrelevant and will be ignored; it +is sufficient to specifiy the \fBt_opthdr\fR part of an option only. The +currently effective values are then returned in \fIreq\(->opt.buf\fR. +.sp +The \fIstatus\fR field returned is \fBT_NOTSUPPORT\fR if the protocol level +does not support this option or the transport user illegally requested a +privileged option, T_READONLY if the option is read-only, and set to +\fBT_SUCCESS\fR in all other cases. The overall result of the request is +returned in \fIret\(->flags\fR. This field contains the worst single result, +whereby the rating is the same as for \fBT_NEGOTIATE.\fR +.sp +For each level, the option \fBT_ALLOPT\fR can be requested on input. All +supported options of this level with their currently effective values are then +returned. +.sp +The option \fBT_ALLOPT\fR can only be used with \fBt_optmgmt()\fR and the +actions \fBT_NEGOTIATE,\fR \fBT_DEFAULT\fR and \fBT_CURRENT.\fR It can be +used with any supported level and addresses all supported options of this +level. The option has no value; it consists of a \fBt_opthdr\fR only. Since +in a \fBt_optmgmt()\fR call only options of one level may be addressed, this +option should not be requested together with other options. The function +returns as soon as this option has been processed. +.sp +Options are independently processed in the order they appear in the input +option buffer. If an option is multiply input, it depends on the implementation +whether it is multiply output or whether it is returned only once. +.sp +Transport providers may not be able to provide an interface capable of +supporting \fBT_NEGOTIATE\fR and/or \fBT_CHECK\fR functionalities. When this +is the case, the error \fBTNOTSUPPORT\fR is returned. +.sp +The function \fBt_optmgmt()\fR may block under various circumstances and +depending on the implementation. The function will block, for instance, if the +protocol addressed by the call resides on a separate controller. It may also +block due to flow control constraints; that is, if data sent previously across +this transport endpoint has not yet been fully processed. If the function is +interrupted by a signal, the option negotiations that have been done so far may +remain valid. The behavior of the function is not changed if \fBO_NONBLOCK\fR +is set. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a value +of \(mi1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADFLAG\fR\fR +.ad +.RS 15n +.rt +An invalid flag was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADOPT\fR\fR +.ad +.RS 15n +.rt +The specified options were in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allowed for an incoming argument \fI(maxlen)\fR is greater +than \fB0\fR but not sufficient to store the value of that argument. The +information to be returned in \fIret\fR will be discarded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This action is not supported by the transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.sp +.in +2 +.nf +#include <tiuser.h> +.fi +.in -2 + +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value \fBTPROTO\fR can be set by the \fBXTI\fR interface but +not by the \fBTLI\fR interface. +.sp +.LP +The \fBt_errno\fR values that this routine can return under different +circumstances than its \fBXTI\fR counterpart are \fBTACCES\fR and +\fBTBUFOVFLW\fR. +.sp +.ne 2 +.mk +.na +\fB\fBTACCES\fR \fR +.ad +.RS 14n +.rt +can be returned to indicate that the user does not have permission to negotiate +the specified options. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR \fR +.ad +.RS 14n +.rt +can be returned even when the \fBmaxlen\fR field of the corresponding buffer +has been set to zero. +.RE + +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. The macros \fBT_OPT_DATA,\fR \fBT_OPT_NEXTHDR,\fR and +\fBT_OPT_FIRSTHDR\fR described for \fBXTI\fR are not available for use by TLI +interfaces. +.SS "Actions" +.sp +.LP +The semantic meaning of various action values for the \fBflags\fR field of +\fIreq\fR differs between the \fBTLI\fR and \fBXTI\fR interfaces. \fBTLI\fR +interface users should heed the following descriptions of the actions: +.sp +.ne 2 +.mk +.na +\fB\fBT_NEGOTIATE\fR \fR +.ad +.RS 16n +.rt +This action enables the user to negotiate the values of the options specified +in \fIreq\fR with the transport provider. The provider will evaluate the +requested options and negotiate the values, returning the negotiated values +through \fIret\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_CHECK\fR \fR +.ad +.RS 16n +.rt +This action enables the user to verify whether the options specified in +\fIreq\fR are supported by the transport provider. On return, the \fBflags\fR +field of \fIret\fR will have either \fBT_SUCCESS\fR or \fBT_FAILURE\fR set to +indicate to the user whether the options are supported. These flags are only +meaningful for the \fBT_CHECK\fR request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_DEFAULT\fR \fR +.ad +.RS 16n +.rt +This action enables a user to retrieve the default options supported by the +transport provider into the \fBopt\fR field of \fIret\fR. In \fIreq\fR, the +\fBlen\fR field of \fBopt\fR must be zero and the \fBbuf\fR field may be +\fINULL\fR. +.RE + +.SS "Connectionless Mode" +.sp +.LP +If issued as part of the connectionless mode service, \fBt_optmgmt()\fR may +block due to flow control constraints. The function will not complete until the +transport provider has processed all previously sent data units. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBpoll\fR(2), \fBselect\fR(3C), \fBt_accept\fR(3NSL), +\fBt_alloc\fR(3NSL), \fBt_bind\fR(3NSL), \fBt_close\fR(3NSL), +\fBt_connect\fR(3NSL), \fBt_getinfo\fR(3NSL), \fBt_listen\fR(3NSL), +\fBt_open\fR(3NSL), \fBt_rcv\fR(3NSL), \fBt_rcvconnect\fR(3NSL), +\fBt_rcvudata\fR(3NSL), \fBt_snddis\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcv.3nsl b/usr/src/man/man3nsl/t_rcv.3nsl new file mode 100644 index 0000000000..1eed95b40d --- /dev/null +++ b/usr/src/man/man3nsl/t_rcv.3nsl @@ -0,0 +1,237 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved. +.\" Portions Copyright 1989 AT&T +.\" Portions Copyright (C) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcv 3NSL "24 Aug 2007" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcv \- receive data or expedited data sent over a connection +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + +\fBint\fR \fBt_rcv\fR(\fBint\fR \fIfd\fR, \fBvoid *\fR\fIbuf\fR, \fBunsigned int\fR \fInbytes\fR, \fBint *\fR\fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR function that has the same name as an \fBXTI\fR function, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function receives either normal or expedited data. The argument \fIfd\fR +identifies the local transport endpoint through which data will arrive, +\fIbuf\fR points to a receive buffer where user data will be placed, and +\fInbytes\fR specifies the size of the receive buffer. The argument \fIflags\fR +may be set on return from \fBt_rcv()\fR and specifies optional flags as +described below. +.sp +.LP +By default, \fBt_rcv()\fR operates in synchronous mode and will wait for data +to arrive if none is currently available. However, if \fBO_NONBLOCK\fR is set +by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_rcv()\fR will execute in +asynchronous mode and will fail if no data is available. See \fBTNODATA\fR +below. +.sp +.LP +On return from the call, if \fBT_MORE\fR is set in \fIflags\fR, this indicates +that there is more data, and the current transport service data unit (TSDU) or +expedited transport service data unit (ETSDU) must be received in multiple +\fBt_rcv()\fR calls. In the asynchronous mode, or under unusual conditions (for +example, the arrival of a signal or \fBT_EXDATA\fR event), the \fBT_MORE\fR +flag may be set on return from the \fBt_rcv()\fR call even when the number of +bytes received is less than the size of the receive buffer specified. Each +\fBt_rcv()\fR with the \fBT_MORE\fR flag set indicates that another +\fBt_rcv()\fR must follow to get more data for the current TSDU. The end of the +TSDU is identified by the return of a \fBt_rcv()\fR call with the \fBT_MORE\fR +flag not set. If the transport provider does not support the concept of a TSDU +as indicated in the \fIinfo\fR argument on return from \fBt_open\fR(3NSL) or +\fBt_getinfo\fR(3NSL), the \fBT_MORE\fR flag is not meaningful and should be +ignored. If \fInbytes\fR is greater than zero on the call to \fBt_rcv()\fR, +\fBt_rcv()\fR will return \fB0\fR only if the end of a TSDU is being returned +to the user. +.sp +.LP +On return, the data is expedited if \fBT_EXPEDITED\fR is set in flags. If +\fBT_MORE\fR is also set, it indicates that the number of expedited bytes +exceeded nbytes, a signal has interrupted the call, or that an entire ETSDU +was not available (only for transport protocols that support fragmentation of +ETSDUs). The rest of the ETSDU will be returned by subsequent calls to +\fBt_rcv()\fR which will return with \fBT_EXPEDITED\fR set in flags. The end +of the ETSDU is identified by the return of a \fBt_rcv()\fR call with +\fBT_EXPEDITED\fR set and \fBT_MORE\fR cleared. If the entire ETSDU is not +available it is possible for normal data fragments to be returned between the +initial and final fragments of an ETSDU. +.sp +.LP +If a signal arrives, \fBt_rcv()\fR returns, giving the user any data currently +available. If no data is available, \fBt_rcv()\fR returns -1, sets +\fBt_errno\fR to \fBTSYSERR\fR and \fBerrno\fR to \fBEINTR\fR. If some data is +available, \fBt_rcv()\fR returns the number of bytes received and +\fBT_MORE\fR is set in flags. +.sp +.LP +In synchronous mode, the only way for the user to be notified of the arrival of +normal or expedited data is to issue this function or check for the +\fBT_DATA\fR or \fBT_EXDATA\fR events using the \fBt_look\fR(3NSL) function. +Additionally, the process can arrange to be notified by means of the EM +interface. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBt_rcv()\fR returns the number of bytes received. +Otherwise, it returns \fB\(mi1\fR on failure and \fBt_errno\fR is set to +indicate the error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_OUTREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but no data is currently available from the transport +provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_getinfo\fR(3NSL), \fBt_look\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_snd\fR(3NSL), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvconnect.3nsl b/usr/src/man/man3nsl/t_rcvconnect.3nsl new file mode 100644 index 0000000000..3bc6e802d0 --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvconnect.3nsl @@ -0,0 +1,240 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvconnect 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvconnect \- receive the confirmation from a connection request +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvconnect\fR(\fBint\fR \fIfd\fR, \fBstruct t_call *\fR\fIcall\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function enables a calling transport user to determine the status of a +previously sent connection request and is used in conjunction with +\fBt_connect\fR(3NSL) to establish a connection in asynchronous mode, and to +complete a synchronous \fBt_connect\fR(3NSL) call that was interrupted by a +signal. The connection will be established on successful completion of this +function. +.sp +.LP +The argument \fIfd\fR identifies the local transport endpoint where +communication will be established, and \fIcall\fR contains information +associated with the newly established connection. The argument \fIcall\fR +points to a \fBt_call\fR structure which contains the following members: +.sp +.in +2 +.nf +\fBstruct netbuf addr; +struct netbuf opt; +struct netbuf udata; +int sequence;\fR +.fi +.in -2 + +.sp +.LP +In \fIcall\fR, \fIaddr\fR returns the protocol address associated with the +responding transport endpoint, \fIopt\fR presents any options associated with +the connection, \fIudata\fR points to optional user data that may be returned +by the destination transport user during connection establishment, and +\fIsequence\fR has no meaning for this function. +.sp +.LP +The \fImaxlen\fR field of each argument must be set before issuing this +function to indicate the maximum size of the buffer for each. However, +\fImaxlen\fR can be set to zero, in which case no information to this specific +argument is given to the user on the return from \fBt_rcvconnect()\fR. If +\fIcall\fR is set to \fINULL,\fR no information at all is returned. By +default, \fBt_rcvconnect()\fR executes in synchronous mode and waits for the +connection to be established before returning. On return, the \fIaddr\fR, +\fIopt\fR and \fIudata\fR fields reflect values associated with the connection. +.sp +.LP +If \fBO_NONBLOCK\fR is set by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), +\fBt_rcvconnect()\fR executes in asynchronous mode, and reduces to a poll for +existing connection confirmations. If none are available, \fBt_rcvconnect()\fR +fails and returns immediately without waiting for the connection to be +established. See \fBTNODATA\fR below. In this case, \fBt_rcvconnect()\fR must +be called again to complete the connection establishment phase and retrieve the +information returned in \fIcall\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_OUTCON\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for an incoming argument \fI(maxlen)\fR is +greater than \fB0\fR but not sufficient to store the value of that argument, +and the connection information to be returned in \fIcall\fR will be discarded. +The provider's state, as seen by the user, will be changed to +\fBT_DATAXFER.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport connection and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but a connection confirmation has not yet arrived. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include<tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value \fBTPROTO\fR can be set by the \fBXTI\fR interface but +not by the \fBTLI\fR interface. +.sp +.LP +A \fBt_errno\fR value that this routine can return under different +circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW\fR. It can be +returned even when the \fBmaxlen\fR field of the corresponding buffer has been +set to zero. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_accept\fR(3NSL), \fBt_alloc\fR(3NSL), \fBt_bind\fR(3NSL), +\fBt_connect\fR(3NSL), \fBt_listen\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_optmgmt\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvdis.3nsl b/usr/src/man/man3nsl/t_rcvdis.3nsl new file mode 100644 index 0000000000..f091b75974 --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvdis.3nsl @@ -0,0 +1,214 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvdis 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvdis \- retrieve information from disconnection +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvdis\fR(\fBint\fR \fIfd\fR, \fBstruct t_discon *\fR\fIdiscon\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is used to identify the cause of a disconnection and to retrieve +any user data sent with the disconnection. The argument \fIfd\fR identifies the +local transport endpoint where the connection existed, and \fIdiscon\fR points +to a \fBt_discon\fR structure containing the following members: +.sp +.in +2 +.nf +struct netbuf udata; +int reason; +int sequence; +.fi +.in -2 + +.sp +.LP +The field \fIreason\fR specifies the reason for the disconnection through a +protocol-dependent reason code, \fIudata\fR identifies any user data that was +sent with the disconnection, and \fIsequence\fR may identify an outstanding +connection indication with which the disconnection is associated. The field +\fIsequence\fR is only meaningful when \fBt_rcvdis()\fR is issued by a passive +transport user who has executed one or more \fBt_listen\fR(3NSL) functions and +is processing the resulting connection indications. If a disconnection +indication occurs, \fIsequence\fR can be used to identify which of the +outstanding connection indications is associated with the disconnection. +.sp +.LP +The \fImaxlen\fR field of \fIudata\fR may be set to zero, if the user does +not care about incoming data. If, in addition, the user does not need to know +the value of \fIreason\fR or \fIsequence\fR, \fIdiscon\fR may be set to +\fINULL\fR and any user data associated with the disconnection indication shall +be discarded. However, if a user has retrieved more than one outstanding +connection indication by means of \fBt_listen\fR(3NSL), and \fIdiscon\fR is a +null pointer, the user will be unable to identify with which connection +indication the disconnection is associated. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_OUTCON\fR, \fBT_OUTREL\fR, \fBT_INREL\fR, +\fBT_INCON(ocnt > 0)\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for incoming data \fI(maxlen)\fR is greater than +\fB0\fR but not sufficient to store the data. If \fIfd\fR is a passive +endpoint with \fIocnt\fR > 1, it remains in state \fBT_INCON;\fR otherwise, +the endpoint state is set to \fBT_IDLE.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODIS\fR\fR +.ad +.RS 15n +.rt +No disconnection indication currently exists on the specified transport +endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values \fBTPROTO\fR and \fBTOUTSTATE\fR can be set by the +\fBXTI\fR interface but not by the \fBTLI\fR interface. +.sp +.LP +A failure return, and a \fBt_errno\fR value that this routine can set under +different circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW.\fR It +can be returned even when the \fBmaxlen\fR field of the corresponding buffer +has been set to zero. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_alloc\fR(3NSL), \fBt_connect\fR(3NSL), \fBt_listen\fR(3NSL), +\fBt_open\fR(3NSL), \fBt_snddis\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvrel.3nsl b/usr/src/man/man3nsl/t_rcvrel.3nsl new file mode 100644 index 0000000000..d0f6038802 --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvrel.3nsl @@ -0,0 +1,191 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvrel 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvrel \- acknowledge receipt of an orderly release indication +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvrel\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is used to receive an orderly release indication for the incoming +direction of data transfer. The argument \fIfd\fR identifies the local +transport endpoint where the connection exists. After receipt of this +indication, the user may not attempt to receive more data by means of +\fBt_rcv\fR(3NSL) or \fBt_rcvv()\fR. Such an attempt will fail with +\fIt_error\fR set to \fBTOUTSTATE\fR. However, the user may continue to send +data over the connection if \fBt_sndrel\fR(3NSL) has not been called by the +user. This function is an optional service of the transport provider, and is +only supported if the transport provider returned service type \fBT_COTS_ORD\fR +on \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). Any user data that may be +associated with the orderly release indication is discarded when +\fBt_rcvrel()\fR is called. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_OUTREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOREL\fR\fR +.ad +.RS 15n +.rt +No orderly release indication currently exists on the specified transport +endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include<tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.br +.in +2 +\fBTOUTSTATE\fR +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), \fBt_sndrel\fR(3NSL), +\fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvreldata.3nsl b/usr/src/man/man3nsl/t_rcvreldata.3nsl new file mode 100644 index 0000000000..744cfad40f --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvreldata.3nsl @@ -0,0 +1,217 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvreldata 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvreldata \- receive an orderly release indication or confirmation +containing user data +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvreldata\fR(\fBint\fR \fIfd\fR, \fBstruct t_discon *\fR\fIdiscon\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function is used to receive an orderly release indication for the incoming +direction of data transfer and to retrieve any user data sent with the release. +The argument \fIfd\fR identifies the local transport endpoint where the +connection exists, and \fIdiscon\fR points to a \fBt_discon\fR structure +containing the following members: +.sp +.in +2 +.nf +struct netbuf udata; +int reason; +int sequence; +.fi +.in -2 + +.sp +.LP +After receipt of this indication, the user may not attempt to receive more +data by means of \fBt_rcv\fR(3NSL) or \fBt_rcvv\fR(3NSL) Such an attempt will +fail with \fIt_error\fR set to \fBTOUTSTATE\fR. However, the user may continue +to send data over the connection if \fBt_sndrel\fR(3NSL) or \fBt_sndreldata\fR +\fB(3N)\fR has not been called by the user. +.sp +.LP +The field \fIreason\fR specifies the reason for the disconnection through a +protocol-dependent \fIreason code\fR, and \fIudata\fR identifies any user +data that was sent with the disconnection; the field \fIsequence\fR is not +used. +.sp +.LP +If a user does not care if there is incoming data and does not need to know the +value of \fIreason\fR, \fIdiscon\fR may be a null pointer, and any user data +associated with the disconnection will be discarded. +.sp +.LP +If \fIdiscon\(->udata.maxlen\fR is greater than zero and less than the length +of the value, \fBt_rcvreldata()\fR fails with \fBt_errno\fR set to +\fBTBUFOVFLW\fR. +.sp +.LP +This function is an optional service of the transport provider, only supported +by providers of service type \fBT_COTS_ORD.\fR The flag \fBT_ORDRELDATA\fR in +the \fIinfo\(->flag\fR field returned by \fBt_open\fR(3NSL) or +\fBt_getinfo\fR(3NSL) indicates that the provider supports orderly release user +data; when the flag is not set, this function behaves like \fBt_rcvrel\fR(3NSL) +and no user data is returned. +.sp +.LP +This function may not be available on all systems. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a value +of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_OUTREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for incoming data (maxlen) is greater than +\fB0\fR but not sufficient to store the data, and the disconnection information +to be returned in \fIdiscon\fR will be discarded. The provider state, as seen +by the user, will be changed as if the data was successfully retrieved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOREL\fR\fR +.ad +.RS 15n +.rt +No orderly release indication currently exists on the specified transport +endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +Orderly release is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), \fBt_sndreldata\fR(3NSL), +\fBt_rcvrel\fR(3NSL), \fBt_sndrel\fR(3NSL), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The interfaces \fBt_sndreldata\fR(3NSL) and \fBt_rcvreldata()\fR are only for +use with a specific transport called "minimal OSI," which is not available on +the Solaris platform. These interfaces are not available for use in conjunction +with Internet Transports (\fBTCP\fR or \fBUDP\fR). diff --git a/usr/src/man/man3nsl/t_rcvudata.3nsl b/usr/src/man/man3nsl/t_rcvudata.3nsl new file mode 100644 index 0000000000..6fb4d9eb68 --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvudata.3nsl @@ -0,0 +1,251 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvudata 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvudata \- receive a data unit +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvudata\fR(\fBint\fR \fIfd\fR, \fBstruct t_unitdata *\fR\fIunitdata\fR, \fBint *\fR\fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is used in connectionless-mode to receive a data unit from +another transport user. The argument \fIfd\fR identifies the local transport +endpoint through which data will be received, \fIunitdata\fR holds information +associated with the received data unit, and \fIflags\fR is set on return to +indicate that the complete data unit was not received. The argument +\fIunitdata\fR points to a \fBt_unitdata\fR structure containing the following +members: +.sp +.in +2 +.nf +\fBstruct netbuf addr; +struct netbuf opt; +struct netbuf udata;\fR +.fi +.in -2 + +.sp +.LP +The \fImaxlen\fR field of \fIaddr\fR, \fIopt\fR and \fIudata\fR must be set +before calling this function to indicate the maximum size of the buffer for +each. If the \fImaxlen\fR field of \fIaddr\fR or \fIopt\fR is set to zero, +no information is returned in the \fIbuf\fR field of this parameter. +.sp +.LP +On return from this call, \fIaddr\fR specifies the protocol address of the +sending user, \fIopt\fR identifies options that were associated with this data +unit, and \fIudata\fR specifies the user data that was received. +.sp +.LP +By default, \fBt_rcvudata()\fR operates in synchronous mode and will wait for a +data unit to arrive if none is currently available. However, if +\fBO_NONBLOCK\fR is set by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), +\fBt_rcvudata()\fR will execute in asynchronous mode and will fail if no data +units are available. +.sp +.LP +If the buffer defined in the \fIudata\fR field of \fIunitdata\fR is not large +enough to hold the current data unit, the buffer will be filled and +\fBT_MORE\fR will be set in \fIflags\fR on return to indicate that another +\fBt_rcvudata()\fR should be called to retrieve the rest of the data unit. +Subsequent calls to \fBt_rcvudata()\fR will return zero for the length of the +address and options until the full data unit has been received. +.sp +.LP +If the call is interrupted, \fBt_rcvudata()\fR will return \fBEINTR\fR and no +datagrams will have been removed from the endpoint. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of \(mi1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for the incoming protocol address or options +\fI(maxlen)\fR is greater than \fB0\fR but not sufficient to store the +information. The unit data information to be returned in \fIunitdata\fR will be +discarded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but no data units are currently available from the +transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include<tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.br +.in +2 +\fBTOUTSTATE\fR +.in -2 +.sp +.LP +A \fBt_errno\fR value that this routine can return under different +circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW.\fR It can be +returned even when the \fBmaxlen\fR field of the corresponding buffer has been +set to zero. +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_alloc\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcvuderr\fR(3NSL), \fBt_sndudata\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvuderr.3nsl b/usr/src/man/man3nsl/t_rcvuderr.3nsl new file mode 100644 index 0000000000..283d0ed021 --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvuderr.3nsl @@ -0,0 +1,217 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvuderr 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvuderr \- receive a unit data error indication +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvuderr\fR(\fBint\fR \fIfd\fR, \fBstruct t_uderr *\fR\fIuderr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is used in connectionless-mode to receive information concerning +an error on a previously sent data unit, and should only be issued following a +unit data error indication. It informs the transport user that a data unit with +a specific destination address and protocol options produced an error. The +argument \fIfd\fR identifies the local transport endpoint through which the +error report will be received, and \fIuderr\fR points to a \fBt_uderr\fR +structure containing the following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +t_scalar_t error; +.fi +.in -2 + +.sp +.LP +The \fImaxlen\fR field of \fIaddr\fR and \fIopt\fR must be set before calling +this function to indicate the maximum size of the buffer for each. If this +field is set to zero for \fIaddr\fR or \fIopt\fR, no information is returned +in the \fIbuf\fR field of this parameter. +.sp +.LP +On return from this call, the \fIaddr\fR structure specifies the destination +protocol address of the erroneous data unit, the \fIopt\fR structure identifies +options that were associated with the data unit, and \fBerror\fR specifies a +protocol-dependent error code. +.sp +.LP +If the user does not care to identify the data unit that produced an error, +\fIuderr\fR may be set to a null pointer, and \fBt_rcvuderr()\fR will simply +clear the error indication without reporting any information to the user. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for the incoming protocol address or options +\fI(maxlen)\fR is greater than 0 but not sufficient to store the information. +The unit data error information to be returned in \fIuderr\fR will be +discarded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOUDERR\fR\fR +.ad +.RS 15n +.rt +No unit data error indication currently exists on the specified transport +endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +\fB#include <tiuser.h>\fR +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values \fBTPROTO\fR and \fBTOUTSTATE\fR can be set by the +\fBXTI\fR interface but not by the \fBTLI\fR interface. +.sp +.LP +A \fBt_errno\fR value that this routine can return under different +circumstances than its \fBXTI\fR counterpart is \fBTBUFOVFLW.\fR It can be +returned even when the \fBmaxlen\fR field of the corresponding buffer has been +set to zero. +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_rcvudata\fR(3NSL), \fBt_sndudata\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvv.3nsl b/usr/src/man/man3nsl/t_rcvv.3nsl new file mode 100644 index 0000000000..3d9ca2006f --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvv.3nsl @@ -0,0 +1,247 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvv 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvv \- receive data or expedited data sent over a connection and put the +data into one or more non-contiguous buffers +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_rcvv\fR(\fBint\fR \fIfd\fR, \fBstruct t_iovec *\fR\fIiov\fR, \fBunsigned int\fR \fIiovcount\fR, \fBint *\fR\fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function receives either normal or expedited data. The argument \fIfd\fR +identifies the local transport endpoint through which data will arrive, +\fIiov\fR points to an array of buffer address/buffer size pairs +(\fIiov_base\fR, \fIiov_len\fR). The \fBt_rcvv()\fR function receives data +into the buffers specified by \fIiov\fR\fB0\fR\fI\&.iov_base\fR, +\fIiov\fR\fB1\fR\fI\&.iov_base\fR, through \fIiov +[iovcount-1].iov_base\fR\fB,\fR always filling one buffer before proceeding to +the next. +.sp +.LP +Note that the limit on the total number of bytes available in all buffers +passed: +.sp +.in +2 +.nf +\fIiov(0).iov_len + . . + iov(iovcount-1).iov_len)\fR +.fi +.in -2 + +.sp +.LP +may be constrained by implementation limits. If no other constraint applies, it +will be limited by \fBINT_MAX\fR. In practice, the availability of memory to an +application is likely to impose a lower limit on the amount of data that can be +sent or received using scatter/gather functions. +.sp +.LP +The argument iovcount contains the number of buffers which is limited to +\fBT_IOV_MAX,\fR which is an implementation-defined value of at least 16. If +the limit is exceeded, the function will fail with \fBTBADDATA\fR. +.sp +.LP +The argument flags may be set on return from \fBt_rcvv()\fR and specifies +optional flags as described below. +.sp +.LP +By default, \fBt_rcvv()\fR operates in synchronous mode and will wait for data +to arrive if none is currently available. However, if \fBO_NONBLOCK\fR is set +by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_rcvv()\fR will execute +in asynchronous mode and will fail if no data is available. See \fBTNODATA\fR +below. +.sp +.LP +On return from the call, if \fBT_MORE\fR is set in flags, this indicates that +there is more data, and the current transport service data unit (TSDU) or +expedited transport service data unit (ETSDU) must be received in multiple +\fBt_rcvv()\fR or \fBt_rcv\fR(3NSL) calls. In the asynchronous mode, or under +unusual conditions (for example, the arrival of a signal or \fBT_EXDATA\fR +event), the \fBT_MORE\fR flag may be set on return from the \fBt_rcvv()\fR +call even when the number of bytes received is less than the total size of all +the receive buffers. Each \fBt_rcvv()\fR with the \fBT_MORE\fR flag set +indicates that another \fBt_rcvv()\fR must follow to get more data for the +current TSDU. The end of the TSDU is identified by the return of a +\fBt_rcvv()\fR call with the \fBT_MORE\fR flag not set. If the transport +provider does not support the concept of a TSDU as indicated in the \fIinfo\fR +argument on return from \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL), the +\fBT_MORE\fR flag is not meaningful and should be ignored. If the amount of +buffer space passed in \fIiov\fR is greater than zero on the call to +\fBt_rcvv()\fR, then \fBt_rcvv()\fR will return \fB0\fR only if the end of a +TSDU is being returned to the user. +.sp +.LP +On return, the data is expedited if \fBT_EXPEDITED\fR is set in flags. If +\fBT_MORE\fR is also set, it indicates that the number of expedited bytes +exceeded nbytes, a signal has interrupted the call, or that an entire ETSDU +was not available (only for transport protocols that support fragmentation of +ETSDUs). The rest of the ETSDU will be returned by subsequent calls to +\fBt_rcvv()\fR which will return with \fBT_EXPEDITED\fR set in flags. The end +of the ETSDU is identified by the return of a \fBt_rcvv()\fR call with +\fBT_EXPEDITED\fR set and \fBT_MORE\fR cleared. If the entire ETSDU is not +available it is possible for normal data fragments to be returned between the +initial and final fragments of an ETSDU. +.sp +.LP +If a signal arrives, \fBt_rcvv()\fR returns, giving the user any data currently +available. If no data is available, \fBt_rcvv()\fR returns -1, sets +\fBt_errno\fR to \fBTSYSERR\fR and \fBerrno\fR to \fBEINTR\fR. If some data is +available, \fBt_rcvv()\fR returns the number of bytes received and +\fBT_MORE\fR is set in flags. +.sp +.LP +In synchronous mode, the only way for the user to be notified of the arrival of +normal or expedited data is to issue this function or check for the +\fBT_DATA\fR \fBor\fR \fBT_EXDATA\fR events using the \fBt_look\fR(3NSL) +function. Additionally, the process can arrange to be notified via the EM +interface. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBt_rcvv()\fR returns the number of bytes received. +Otherwise, it returns -1 on failure and \fBt_errno\fR is set to indicate the +error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_OUTREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +\fIiovcount\fR is greater than \fBT_IOV_MAX.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but no data is currently available from the transport +provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_getinfo\fR(3NSL), \fBt_look\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcv\fR(3NSL), \fBt_snd\fR(3NSL), \fBt_sndv\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_rcvvudata.3nsl b/usr/src/man/man3nsl/t_rcvvudata.3nsl new file mode 100644 index 0000000000..a7d16838ef --- /dev/null +++ b/usr/src/man/man3nsl/t_rcvvudata.3nsl @@ -0,0 +1,244 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_rcvvudata 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_rcvvudata \- receive a data unit into one or more noncontiguous buffers +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_rcvvudata\fR(\fBint\fR \fIfd\fR, \fBstruct t_unitdata *\fR\fIunitdata\fR, \fBstruct t_iovec *\fR\fIiov\fR, + \fBunsigned int\fR \fIiovcount\fR, \fBint *\fR\fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function is used in connectionless mode to receive a data unit from +another transport user. The argument \fIfd\fR identifies the local transport +endpoint through which data will be received, \fIunitdata\fR holds information +associated with the received data unit, \fIiovcount\fR contains the number of +non-contiguous udata buffers which is limited to \fBT_IOV_MAX,\fR which is an +implementation-defined value of at least 16, and \fIflags\fR is set on return +to indicate that the complete data unit was not received. If the limit on +\fIiovcount\fR is exceeded, the function fails with \fBTBADDATA\fR. The +argument \fIunitdata\fR points to a \fBt_unitdata\fR structure containing the +following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +struct netbuf udata; +.fi +.in -2 + +.sp +.LP +The \fImaxlen\fR field of \fIaddr\fR and \fIopt\fR must be set before +calling this function to indicate the maximum size of the buffer for each. The +\fIudata\fR field of \fBt_unitdata\fR is not used. The \fIiov_len\fR and +\fIiov_base\fR fields of "\fIiov\fR\fB0\fR" through \fIiov [iovcount-1]\fR +must be set before calling \fBt_rcvvudata()\fR to define the buffer where the +userdata will be placed. If the maxlen field of \fIaddr\fR or \fIopt\fR is +set to zero then no information is returned in the \fIbuf\fR field for this +parameter. +.sp +.LP +On return from this call, \fIaddr\fR specifies the protocol address of the +sending user, \fIopt\fR identifies options that were associated with this data +unit, and \fIiov\fR\fB[0]\fR\fI\&.iov_base\fR through \fIiov +[iovcount-1].iov_base\fR contains the user data that was received. The return +value of \fBt_rcvvudata()\fR is the number of bytes of user data given to the +user. +.sp +.LP +Note that the limit on the total number of bytes available in all buffers +passed: +.sp +.in +2 +.nf +\fIiov(0).iov_len + . . + iov(iovcount-1).iov_len\fR) +.fi +.in -2 + +.sp +.LP +may be constrained by implementation limits. If no other constraint applies, it +will be limited by \fBINT_MAX\fR. In practice, the availability of memory to an +application is likely to impose a lower limit on the amount of data that can be +sent or received using scatter/gather functions. +.sp +.LP +By default, \fBt_rcvvudata()\fR operates in synchronous mode and waits for a +data unit to arrive if none is currently available. However, if +\fBO_NONBLOCK\fR is set by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), +\fBt_rcvvudata()\fR executes in asynchronous mode and fails if no data units +are available. +.sp +.LP +If the buffers defined in the \fIiov[]\fR array are not large enough to hold +the current data unit, the buffers will be filled and \fBT_MORE\fR will be set +in flags on return to indicate that another \fBt_rcvvudata()\fR should be +called to retrieve the rest of the data unit. Subsequent calls to +\fBt_rcvvudata()\fR will return zero for the length of the address and options, +until the full data unit has been received. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBt_rcvvudata()\fR returns the number of bytes +received. Otherwise, it returns -1 on failure and \fBt_errno\fR is set to +indicate the error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +\fIiovcount\fR is greater than \fBT_IOV_MAX.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBUFOVFLW\fR\fR +.ad +.RS 15n +.rt +The number of bytes allocated for the incoming protocol address or options +(\fImaxlen\fR) is greater than \fB0\fR but not sufficient to store the +information. The unit data information to be returned in \fIunitdata\fR will +be discarded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNODATA\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but no data units are currently available from the +transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_alloc\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcvudata\fR(3NSL), \fBt_rcvuderr\fR(3NSL), \fBt_sndudata\fR(3NSL), +\fBt_sndvudata\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_snd.3nsl b/usr/src/man/man3nsl/t_snd.3nsl new file mode 100644 index 0000000000..1b46f38278 --- /dev/null +++ b/usr/src/man/man3nsl/t_snd.3nsl @@ -0,0 +1,366 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_snd 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_snd \- send data or expedited data over a connection +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_snd\fR(\fBint\fR \fIfd\fR, \fBvoid *\fR\fIbuf\fR, \fBunsigned int\fR \fInbytes\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is used to send either normal or expedited data. The argument +\fIfd\fR identifies the local transport endpoint over which data should be +sent, \fIbuf\fR points to the user data, \fInbytes\fR specifies the number of +bytes of user data to be sent, and \fIflags\fR specifies any optional flags +described below: +.sp +.ne 2 +.mk +.na +\fB\fBT_EXPEDITED\fR \fR +.ad +.RS 16n +.rt +If set in \fIflags\fR, the data will be sent as expedited data and will be +subject to the interpretations of the transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_MORE\fR \fR +.ad +.RS 16n +.rt +If set in \fIflags\fR, this indicates to the transport provider that the +transport service data unit (TSDU) (or expedited transport service data unit - +ETSDU) is being sent through multiple \fBt_snd()\fR calls. Each \fBt_snd()\fR +with the \fBT_MORE\fR flag set indicates that another \fBt_snd()\fR will +follow with more data for the current TSDU (or ETSDU). +.sp +The end of the TSDU (or ETSDU) is identified by a \fBt_snd()\fR call with the +\fBT_MORE\fR flag not set. Use of \fBT_MORE\fR enables a user to break up +large logical data units without losing the boundaries of those units at the +other end of the connection. The flag implies nothing about how the data is +packaged for transfer below the transport interface. If the transport provider +does not support the concept of a TSDU as indicated in the \fIinfo\fR argument +on return from \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL), the \fBT_MORE\fR +flag is not meaningful and will be ignored if set. +.sp +The sending of a zero-length fragment of a TSDU or ETSDU is only permitted +where this is used to indicate the end of a TSDU or ETSDU; that is, when the +\fBT_MORE\fR flag is not set. Some transport providers also forbid zero-length +TSDUs and ETSDUs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_PUSH\fR \fR +.ad +.RS 16n +.rt +If set in \fIflags\fR, requests that the provider transmit all data that it has +accumulated but not sent. The request is a local action on the provider and +does not affect any similarly named protocol flag (for example, the TCP PUSH +flag). This effect of setting this flag is protocol\(hydependent, and it may be +ignored entirely by transport providers which do not support the use of this +feature. +.RE + +.sp +.LP +Note that the communications provider is free to collect data in a send buffer +until it accumulates a sufficient amount for transmission. +.sp +.LP +By default, \fBt_snd()\fR operates in synchronous mode and may wait if flow +control restrictions prevent the data from being accepted by the local +transport provider at the time the call is made. However, if \fBO_NONBLOCK\fR +is set by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_snd()\fR will +execute in asynchronous mode, and will fail immediately if there are flow +control restrictions. The process can arrange to be informed when the flow +control restrictions are cleared by means of either \fBt_look\fR(3NSL) or the +EM interface. +.sp +.LP +On successful completion, \fBt_snd()\fR returns the number of bytes (octets) +accepted by the communications provider. Normally this will equal the number +of octets specified in nbytes. However, if \fBO_NONBLOCK\fR is set or the +function is interrupted by a signal, it is possible that only part of the data +has actually been accepted by the communications provider. In this case, +\fBt_snd()\fR returns a value that is less than the value of nbytes. If +\fBt_snd()\fR is interrupted by a signal before it could transfer data to the +communications provider, it returns -1 with \fBt_errno\fR set to +\fBTSYSERR\fR and \fBerrno\fR set to \fBEINTR\fR. +.sp +.LP +If nbytes is zero and sending of zero bytes is not supported by the underlying +communications service, \fBt_snd()\fR returns \(mi1 with \fBt_errno\fR set to +\fBTBADDATA\fR. +.sp +.LP +The size of each TSDU or ETSDU must not exceed the limits of the transport +provider as specified by the current values in the TSDU or ETSDU fields in the +\fIinfo\fR argument returned by \fBt_getinfo\fR(3NSL). +.sp +.LP +The error \fBTLOOK\fR is returned for asynchronous events. It is required only +for an incoming disconnect event but may be returned for other events. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBt_snd()\fR returns the number of bytes accepted by +the transport provider. Otherwise, -1 is returned on failure and \fBt_errno\fR +is set to indicate the error. +.sp +.LP +Note that if the number of bytes accepted by the communications provider is +less than the number of bytes requested, this may either indicate that +\fBO_NONBLOCK\fR is set and the communications provider is blocked due to flow +control, or that \fBO_NONBLOCK\fR is clear and the function was interrupted by +a signal. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +Illegal amount of data: +.RS +4 +.TP +.ie t \(bu +.el o +A single send was attempted specifying a TSDU (ETSDU) or fragment TSDU (ETSDU) +greater than that specified by the current values of the TSDU or ETSDU fields +in the \fIinfo\fR argument. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A send of a zero byte TSDU (ETSDU) or zero byte fragment of a TSDU (ETSDU) is +not supported by the provider. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Multiple sends were attempted resulting in a TSDU (ETSDU) larger than that +specified by the current value of the TSDU or ETSDU fields in the \fIinfo\fR +argument - the ability of an XTI implementation to detect such an error case is +implementation-dependent. See \fBWARNINGS\fR, below. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADFLAG\fR\fR +.ad +.RS 15n +.rt +An invalid flag was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTFLOW\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but the flow control mechanism prevented the +transport provider from accepting any data at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.br +.in +2 +\fBTLOOK\fR +.in -2 +.br +.in +2 +\fBTBADFLAG\fR +.in -2 +.br +.in +2 +\fBTOUTSTATE\fR +.in -2 +.sp +.LP +The \fBt_errno\fR values that this routine can return under different +circumstances than its \fBXTI\fR counterpart are: +.br +.in +2 +\fBTBADDATA\fR +.in -2 +.sp +.LP +In the \fBTBADDATA\fR error cases described above, \fBTBADDATA\fR is returned, +only for illegal zero byte \fBTSDU\fR ( \fBETSDU\fR) send attempts. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_getinfo\fR(3NSL), \fBt_look\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcv\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +It is important to remember that the transport provider treats all users of a +transport endpoint as a single user. Therefore if several processes issue +concurrent \fBt_snd()\fR calls then the different data may be intermixed. +.sp +.LP +Multiple sends which exceed the maximum TSDU or ETSDU size may not be +discovered by XTI. In this case an implementation-dependent error will result, +generated by the transport provider, perhaps on a subsequent XTI call. This +error may take the form of a connection abort, a \fBTSYSERR\fR, a +\fBTBADDATA\fR or a \fBTPROTO\fR error. +.sp +.LP +If multiple sends which exceed the maximum TSDU or ETSDU size are detected by +XTI, \fBt_snd()\fR fails with \fBTBADDATA\fR. diff --git a/usr/src/man/man3nsl/t_snddis.3nsl b/usr/src/man/man3nsl/t_snddis.3nsl new file mode 100644 index 0000000000..191c7d8505 --- /dev/null +++ b/usr/src/man/man3nsl/t_snddis.3nsl @@ -0,0 +1,230 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_snddis 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_snddis \- send user-initiated disconnection request +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_snddis\fR(\fBint\fR \fIfd\fR, \fBconst struct t_call *\fR\fIcall\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the TLI COMPATIBILITY +section for a description of differences between the two interfaces. +.sp +.LP +This function is used to initiate an abortive release on an already established +connection, or to reject a connection request. The argument \fIfd\fR identifies +the local transport endpoint of the connection, and \fIcall\fR specifies +information associated with the abortive release. The argument \fIcall\fR +points to a \fBt_call\fR structure which contains the following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +struct netbuf udata; +int sequence; +.fi +.in -2 + +.sp +.LP +The values in \fIcall\fR have different semantics, depending on the context of +the call to \fBt_snddis()\fR. When rejecting a connection request, \fIcall\fR +must be non-null and contain a valid value of \fIsequence\fR to uniquely +identify the rejected connection indication to the transport provider. The +\fIsequence\fR field is only meaningful if the transport connection is in the +\fBT_INCON\fR state. The \fIaddr\fR and \fIopt\fR fields of \fIcall\fR are +ignored. In all other cases, \fIcall\fR need only be used when data is being +sent with the disconnection request. The \fIaddr\fR, \fIopt\fR and +\fIsequence\fR fields of the \fBt_call\fR structure are ignored. If the user +does not wish to send data to the remote user, the value of \fIcall\fR may be a +null pointer. +.sp +.LP +The \fIudata\fR structure specifies the user data to be sent to the remote +user. The amount of user data must not exceed the limits supported by the +transport provider, as returned in the \fIdiscon\fR field, of the \fIinfo\fR +argument of \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). If the \fIlen\fR field +of \fIudata\fR is zero, no data will be sent to the remote user. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_OUTCON\fR, \fBT_OUTREL\fR, \fBT_INREL\fR, +\fBT_INCON(ocnt > 0)\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +The amount of user data specified was not within the bounds allowed by the +transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADSEQ\fR\fR +.ad +.RS 15n +.rt +An invalid sequence number was specified, or a null \fIcall\fR pointer was +specified, when rejecting a connection request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event, which requires attention, has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable \fBX\fRTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +\fB#include <tiuser.h>\fR +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value \fBTPROTO\fR can be set by the \fBXTI\fR interface but +not by the \fBTLI\fR interface. +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_connect\fR(3NSL), \fBt_getinfo\fR(3NSL), \fBt_listen\fR(3NSL), +\fBt_open\fR(3NSL), \fBt_snd\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +\fBt_snddis()\fR is an abortive disconnection. Therefore a \fBt_snddis()\fR +issued on a connection endpoint may cause data previously sent by means of +\fBt_snd\fR(3NSL), or data not yet received, to be lost, even if an error is +returned. diff --git a/usr/src/man/man3nsl/t_sndrel.3nsl b/usr/src/man/man3nsl/t_sndrel.3nsl new file mode 100644 index 0000000000..79d04a2ada --- /dev/null +++ b/usr/src/man/man3nsl/t_sndrel.3nsl @@ -0,0 +1,197 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sndrel 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sndrel \- initiate an orderly release +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_sndrel\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +For transport providers of type \fBT_COTS_ORD,\fR this function is used to +initiate an orderly release of the outgoing direction of data transfer and +indicates to the transport provider that the transport user has no more data to +send. The argument \fIfd\fR identifies the local transport endpoint where the +connection exists. After calling \fBt_sndrel()\fR, the user may not send any +more data over the connection. However, a user may continue to receive data if +an orderly release indication has not been received. For transport providers of +types other than \fBT_COTS_ORD,\fR this function fails with error +\fBTNOTSUPPORT\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is \fBreturned\fR and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_INREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTFLOW\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but the flow control mechanism prevented the +transport provider from accepting the function at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.br +.in +2 +\fBTLOOK\fR +.in -2 +.br +.in +2 +\fBTOUTSTATE\fR +.in -2 +.SS "Notes" +.sp +.LP +Whenever this function fails with \fBt_error\fR set to \fBTFLOW,\fR +\fBO_NONBLOCK\fR must have been set. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_error\fR(3NSL), \fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcvrel\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_sndreldata.3nsl b/usr/src/man/man3nsl/t_sndreldata.3nsl new file mode 100644 index 0000000000..fb571932d1 --- /dev/null +++ b/usr/src/man/man3nsl/t_sndreldata.3nsl @@ -0,0 +1,216 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sndreldata 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sndreldata \- initiate or respond to an orderly release with user data +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_sndreldata\fR(\fBint\fR \fIfd\fR, \fBstruct t_discon *\fR\fIdiscon\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function is used to initiate an orderly release of the outgoing direction +of data transfer and to send user data with the release. The argument +\fIfd\fR identifies the local transport endpoint where the connection exists, +and \fIdiscon\fR points to a \fB t_discon\fR structure containing the +following members: +.sp +.in +2 +.nf +struct netbuf udata; +int reason; +int sequence; +.fi +.in -2 + +.sp +.LP +After calling \fBt_sndreldata()\fR, the user may not send any more data over +the connection. However, a user may continue to receive data if an orderly +release indication has not been received. +.sp +.LP +The field \fIreason\fR specifies the reason for the disconnection through a +protocol-dependent \fIreason code\fR, and \fIudata\fR identifies any user +data that is sent with the disconnection; the field \fIsequence\fR is not +used. +.sp +.LP +The \fIudata\fR structure specifies the user data to be sent to the remote +user. The amount of user data must not exceed the limits supported by the +transport provider, as returned in the \fIdiscon\fR field of the \fIinfo\fR +argument of \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL). If the \fIlen\fR +field of \fIudata\fR is zero or if the provider did not return +\fBT_ORDRELDATA\fR in the \fBt_open\fR(3NSL) flags, no data will be sent to +the remote user. +.sp +.LP +If a user does not wish to send data and reason code to the remote user, the +value of \fIdiscon\fR may be a null pointer. +.sp +.LP +This function is an optional service of the transport provider, only supported +by providers of service type \fBT_COTS_ORD.\fR The flag \fBT_ORDRELDATA\fR in +the \fIinfo\(->flag\fR field returned by \fBt_open\fR(3NSL) or +\fBt_getinfo\fR(3NSL) indicates that the provider supports orderly release user +data. +.sp +.LP +This function may not be available on all systems. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_INREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +The amount of user data specified was not within the bounds allowed by the +transport provider, or user data was supplied and the provider did not return +\fBT_ORDRELDATA\fR in the \fBt_open\fR(3NSL) flags. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTFLOW\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but the flow control mechanism prevented the +transport provider from accepting the function at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint and requires +immediate attention. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +Orderly release is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), \fBt_rcvrel\fR(3NSL), +\fBt_rcvreldata\fR(3NSL), \fBt_sndrel\fR(3NSL), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The interfaces \fBt_sndreldata()\fR and \fBt_rcvreldata\fR(3NSL) are only for +use with a specific transport called "minimal OSI," which is not available on +the Solaris platform. These interfaces are not available for use in conjunction +with Internet Transports (\fBTCP\fR or \fBUDP\fR). diff --git a/usr/src/man/man3nsl/t_sndudata.3nsl b/usr/src/man/man3nsl/t_sndudata.3nsl new file mode 100644 index 0000000000..d7a8082061 --- /dev/null +++ b/usr/src/man/man3nsl/t_sndudata.3nsl @@ -0,0 +1,294 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sndudata 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sndudata \- send a data unit +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_sndudata\fR(\fBint\fR \fIfd\fR, \fBconst struct t_unitdata *\fR\fIunitdata\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +This function is used in connectionless-mode to send a data unit to another +transport user. The argument \fIfd\fR identifies the local transport endpoint +through which data will be sent, and \fIunitdata\fR points to a +\fBt_unitdata\fR structure containing the following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +struct netbuf udata; +.fi +.in -2 + +.sp +.LP +In \fIunitdata\fR, \fIaddr\fR specifies the protocol address of the destination +user, \fIopt\fR identifies options that the user wants associated with this +request, and \fIudata\fR specifies the user data to be sent. The user may +choose not to specify what protocol options are associated with the transfer by +setting the \fIlen\fR field of \fIopt\fR to zero. In this case, the provider +uses the option values currently set for the communications endpoint. +.sp +.LP +If the \fIlen\fR field of \fIudata\fR is zero, and sending of zero octets is +not supported by the underlying transport service, the \fBt_sndudata()\fR will +return -1 with \fBt_errno\fR set to \fBTBADDATA\fR. +.sp +.LP +By default, \fBt_sndudata()\fR operates in synchronous mode and may wait if +flow control restrictions prevent the data from being accepted by the local +transport provider at the time the call is made. However, if \fBO_NONBLOCK\fR +\fBis\fR \fBset\fR \fBby\fR \fBmeans\fR \fBof\fR \fBt_open\fR(3NSL) or +\fBfcntl\fR(2), \fBt_sndudata()\fR will execute in asynchronous mode and will +fail under such conditions. The process can arrange to be notified of the +clearance of a flow control restriction by means of either \fBt_look\fR(3NSL) +or the EM interface. +.sp +.LP +If the amount of data specified in \fIudata\fR exceeds the TSDU size as +returned in the \fItsdu\fR field of the \fIinfo\fR argument of +\fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL), a \fBTBADDATA\fR error will be +generated. If \fBt_sndudata()\fR is called before the destination user has +activated its transport endpoint (see \fBt_bind\fR(3NSL)), the data unit may be +discarded. +.sp +.LP +If it is not possible for the transport provider to immediately detect the +conditions that cause the errors \fBTBADDADDR\fR and \fBTBADOPT\fR, these +errors will alternatively be returned by \fIt_rcvuderr.\fR Therefore, an +application must be prepared to receive these errors in both of these ways. +.sp +.LP +If the call is interrupted, \fBt_sndudata()\fR will return \fBEINTR\fR and the +datagram will not be sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADADDR\fR\fR +.ad +.RS 15n +.rt +The specified protocol address was in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +Illegal amount of data. A single send was attempted specifying a TSDU greater +than that specified in the \fIinfo\fR argument, or a send of a zero byte TSDU +is not supported by the provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADOPT\fR\fR +.ad +.RS 15n +.rt +The specified options were in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTFLOW\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but the flow control mechanism prevented the +transport provider from accepting any data at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h.\fR \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR values that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface are: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.br +.in +2 +\fBTBADADDR\fR +.in -2 +.br +.in +2 +\fBTBADOPT\fR +.in -2 +.br +.in +2 +\fBTLOOK\fR +.in -2 +.br +.in +2 +\fBTOUTSTATE\fR +.in -2 +.SS "Notes" +.sp +.LP +Whenever this function fails with \fBt_error\fR set to \fBTFLOW,\fR +\fBO_NONBLOCK\fR must have been set. +.SS "Option Buffers" +.sp +.LP +The format of the options in an \fBopt\fR buffer is dictated by the transport +provider. Unlike the \fBXTI\fR interface, the \fBTLI\fR interface does not fix +the buffer format. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_alloc\fR(3NSL), \fBt_bind\fR(3NSL), \fBt_error\fR(3NSL), +\fBt_getinfo\fR(3NSL), \fBt_look\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcvudata\fR(3NSL), \fBt_rcvuderr\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_sndv.3nsl b/usr/src/man/man3nsl/t_sndv.3nsl new file mode 100644 index 0000000000..077d84468d --- /dev/null +++ b/usr/src/man/man3nsl/t_sndv.3nsl @@ -0,0 +1,361 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sndv 3NSL "23 Aug 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sndv \- send data or expedited data, from one or more non-contiguous buffers, +on a connection +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_sndv\fR(\fBint\fR \fIfd\fR, \fBconst struct t_iovec *\fR\fIiov\fR, \fBunsigned int\fR \fIiovcount\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function is used to send either normal or expedited data. The argument +\fIfd\fR identifies the local transport endpoint over which data should be +sent, \fIiov\fR points to an array of buffer address/buffer length pairs. +\fBt_sndv()\fR sends data contained in buffers \fIiov\fR\fB0\fR\fI , \fR +\fIiov\fR\fB1\fR\fI ,\fR through \fIiov [iovcount-1]\fR\fB\&.\fR +\fIiovcount\fR contains the number of non-contiguous data buffers which is +limited to \fBT_IOV_MAX\fR, an implementation-defined value of at least 16. +If the limit is exceeded, the function fails with \fBTBADDATA\fR. +.sp +.in +2 +.nf +\fIiov(0).iov_len + . . + iov(iovcount-1).iov_len\fR) +.fi +.in -2 + +.sp +.LP +Note that the limit on the total number of bytes available in all buffers +passed: +.sp +.LP +may be constrained by implementation limits. If no other constraint applies, it +will be limited by \fBINT_MAX\fR. In practice, the availability of memory to an +application is likely to impose a lower limit on the amount of data that can be +sent or received using scatter/gather functions. +.sp +.LP +The argument \fIflags\fR specifies any optional flags described below: +.sp +.ne 2 +.mk +.na +\fB\fBT_EXPEDITED\fR \fR +.ad +.RS 16n +.rt +If set in \fIflags\fR, the data will be sent as expedited data and will be +subject to the interpretations of the transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_MORE\fR \fR +.ad +.RS 16n +.rt +If set in \fIflags\fR, this indicates to the transport provider that the +transport service data unit (TSDU) (or expedited transport service data unit - +ETSDU) is being sent through multiple \fBt_sndv()\fR calls. Each +\fBt_sndv()\fR with the \fBT_MORE\fR flag set indicates that another +\fBt_sndv()\fR or \fBt_snd\fR(3NSL) will follow with more data for the current +TSDU (or ETSDU). +.RE + +.sp +.LP +The end of the TSDU (or ETSDU) is identified by a \fBt_sndv()\fR call with the +\fBT_MORE\fR flag not set. Use of \fBT_MORE\fR enables a user to break up +large logical data units without losing the boundaries of those units at the +other end of the connection. The flag implies nothing about how the data is +packaged for transfer below the transport interface. If the transport provider +does not support the concept of a TSDU as indicated in the \fIinfo\fR argument +on return from \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL), the \fBT_MORE\fR +flag is not meaningful and will be ignored if set. +.sp +.LP +The sending of a zero-length fragment of a TSDU or ETSDU is only permitted +where this is used to indicate the end of a TSDU or ETSDU, that is, when the +\fBT_MORE\fR flag is not set. Some transport providers also forbid zero-length +TSDUs and ETSDUs. +.sp +.LP +If set in \fIflags\fR, requests that the provider transmit all data that it has +accumulated but not sent. The request is a local action on the provider and +does not affect any similarly named protocol flag (for example, the TCP PUSH +flag). This effect of setting this flag is protocol\(hydependent, and it may be +ignored entirely by transport providers which do not support the use of this +feature. +.sp +.LP +The communications provider is free to collect data in a send buffer until it +accumulates a sufficient amount for transmission. +.sp +.LP +By default, \fBt_sndv()\fR operates in synchronous mode and may wait if flow +control restrictions prevent the data from being accepted by the local +transport provider at the time the call is made. However, if \fBO_NONBLOCK\fR +is set by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_sndv()\fR +executes in asynchronous mode, and will fail immediately if there are flow +control restrictions. The process can arrange to be informed when the flow +control restrictions are cleared via either \fBt_look\fR(3NSL) or the EM +interface. +.sp +.LP +On successful completion, \fBt_sndv()\fR returns the number of bytes accepted +by the transport provider. Normally this will equal the total number of bytes +to be sent, that is, +.sp +.in +2 +.nf +\fI(iov\fR\fB0.iov_len + .. + iov[iovcount-1].iov_len)\fR +.fi +.in -2 + +.sp +.LP +However, the interface is constrained to send at most \fBINT_MAX\fR bytes in a +single send. When \fBt_sndv()\fR has submitted \fBINT_MAX\fR (or lower +constrained value, see the note above) bytes to the provider for a single call, +this value is returned to the user. However, if \fBO_NONBLOCK\fR is set or +the function is interrupted by a signal, it is possible that only part of the +data has actually been accepted by the communications provider. In this case, +\fBt_sndv()\fR returns a value that is less than the value of nbytes. If +\fBt_sndv()\fR is interrupted by a signal before it could transfer data to the +communications provider, it returns -1 \fBwith\fR \fBt_errno\fR set to +\fBTSYSERR\fR and \fBerrno\fR set to \fBEINTR\fR. +.sp +.LP +If the number of bytes of data in the \fIiov\fR array is zero and sending of +zero octets is not supported by the underlying transport service, +\fBt_sndv()\fR returns -1 \fBwith\fR \fBt_errno\fR set to \fBTBADDATA\fR. +.sp +.LP +The size of each TSDU or ETSDU must not exceed the limits of the transport +provider as specified by the current values in the TSDU or ETSDU fields in the +\fIinfo\fR argument returned by \fBt_getinfo\fR(3NSL). +.sp +.LP +The error \fBTLOOK\fR is returned for asynchronous events. It is required only +for an incoming disconnect event but may be returned for other events. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBt_sndv()\fR returns the number of bytes accepted +by the transport provider. Otherwise, -1 is returned on failure and +\fBt_errno\fR is set to indicate the error. +.sp +.LP +Note that in synchronous mode, if more than \fBINT_MAX\fR bytes of data are +passed in the \fIiov\fR array, only the first \fBINT_MAX\fR bytes will be +passed to the provider. +.sp +.LP +If the number of bytes accepted by the communications provider is less than the +number of bytes requested, this may either indicate that \fBO_NONBLOCK\fR is +set and the communications provider is blocked due to flow control, or that +\fBO_NONBLOCK\fR is clear and the function was interrupted by a signal. +.SH VALID STATES +.sp +.LP +\fBT_DATAXFER\fR, \fBT_INREL\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 12n +.rt +Illegal amount of data: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RS +4 +.TP +.ie t \(bu +.el o +A single send was attempted specifying a TSDU (ETSDU) or fragment TSDU (ETSDU) +greater than that specified by the current values of the TSDU or ETSDU fields +in the \fIinfo\fR argument. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A send of a zero byte TSDU (ETSDU) or zero byte fragment of a TSDU (ETSDU) is +not supported by the provider. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Multiple sends were attempted resulting in a TSDU (ETSDU) larger than that +specified by the current value of the TSDU or ETSDU fields in the \fIinfo\fR +argument - the ability of an XTI implementation to detect such an error case is +implementation-dependent. See \fBWARNINGS\fR, below. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fIiovcount\fR is greater than \fBT_IOV_MAX.\fR +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADFLAG\fR\fR +.ad +.RS 15n +.rt +An invalid flag was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTFLOW\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR was set, but the flow control mechanism prevented the +transport provider from accepting any data at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_getinfo\fR(3NSL), \fBt_open\fR(3NSL), \fBt_rcvv\fR(3NSL) +\fBt_rcv\fR(3NSL), \fBt_snd\fR(3NSL), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +It is important to remember that the transport provider treats all users of a +transport endpoint as a single user. Therefore if several processes issue +concurrent \fBt_sndv()\fR or \fBt_snd\fR(3NSL) calls, then the different data +may be intermixed. +.sp +.LP +Multiple sends which exceed the maximum TSDU or ETSDU size may not be +discovered by XTI. In this case an implementation-dependent error will result +(generated by the transport provider), perhaps on a subsequent XTI call. This +error may take the form of a connection abort, a \fBTSYSERR\fR, a +\fBTBADDATA\fR or a \fBTPROTO\fR error. +.sp +.LP +If multiple sends which exceed the maximum TSDU or ETSDU size are detected by +XTI, \fBt_sndv()\fR fails with \fBTBADDATA\fR. diff --git a/usr/src/man/man3nsl/t_sndvudata.3nsl b/usr/src/man/man3nsl/t_sndvudata.3nsl new file mode 100644 index 0000000000..f72a3ef7ab --- /dev/null +++ b/usr/src/man/man3nsl/t_sndvudata.3nsl @@ -0,0 +1,273 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved +.\" Portions Copyright 1989 AT&T +.\" Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sndvudata 3NSL "23 Aug 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sndvudata \- send a data unit from one or more noncontiguous buffers +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBint\fR \fBt_sndvudata\fR(\fBint\fR \fIfd\fR, \fBstruct t_unitdata *\fR\fIunitdata\fR, \fBstruct t_iovec *\fR\fIiov\fR, + \fBunsigned int\fR \fIiovcount\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function is used in connectionless mode to send a data unit to another +transport user. The argument \fIfd\fR identifies the local transport endpoint +through which data will be sent, \fIiovcount\fR contains the number of +non-contiguous \fIudata\fR buffers and is limited to an implementation-defined +value given by \fBT_IOV_MAX\fR which is at least 16, and \fIunitdata\fR +points to a \fBt_unitdata\fR structure containing the following members: +.sp +.in +2 +.nf +struct netbuf addr; +struct netbuf opt; +struct netbuf udata; +.fi +.in -2 + +.sp +.LP +If the limit on \fIiovcount\fR is exceeded, the function fails with +\fBTBADDATA\fR. +.sp +.LP +In \fBunitdata\fR, \fIaddr\fR specifies the protocol address of the +destination user, and \fIopt\fR identifies options that the user wants +associated with this request. The \fIudata\fR field is not used. The user may +choose not to specify what protocol options are associated with the transfer by +setting the \fIlen\fR field of \fIopt\fR to zero. In this case, the provider +may use default options. +.sp +.LP +The data to be sent is identified by \fIiov\fR\fB[0]\fR\fI\fR through \fIiov +[iovcount-1]\fR\fB\&.\fR +.sp +.LP +Note that the limit on the total number of bytes available in all buffers +passed: +.sp +.in +2 +.nf +\fIiov(0).iov_len + . . + iov(iovcount-1).iov_len \fR +.fi +.in -2 + +.sp +.LP +may be constrained by implementation limits. If no other constraint applies, it +will be limited by \fBINT_MAX\fR. In practice, the availability of memory to an +application is likely to impose a lower limit on the amount of data that can be +sent or received using scatter/gather functions. +.sp +.LP +By default, \fBt_sndvudata()\fR operates in synchronous mode and may wait if +flow control restrictions prevent the data from being accepted by the local +transport provider at the time the call is made. However, if \fBO_NONBLOCK\fR +is set by means of \fBt_open\fR(3NSL) or \fBfcntl\fR(2), \fBt_sndvudata()\fR +executes in asynchronous mode and will fail under such conditions. The process +can arrange to be notified of the clearance of a flow control restriction by +means of either \fBt_look\fR(3NSL) or the EM interface. +.sp +.LP +If the amount of data specified in \fIiov\fR\fB0\fR\fI\fR through \fIiov +[iovcount-1]\fR exceeds the TSDU size as returned in the \fItsdu\fR field of +the \fIinfo\fR argument of \fBt_open\fR(3NSL) or \fBt_getinfo\fR(3NSL), or is +zero and sending of zero octets is not supported by the underlying transport +service, a \fBTBADDATA\fR error is generated. If \fBt_sndvudata()\fR is +called before the destination user has activated its transport endpoint (see +\fBt_bind\fR(3NSL)\|), the data unit may be discarded. +.sp +.LP +If it is not possible for the transport provider to immediately detect the +conditions that cause the errors \fBTBADDADDR\fR and \fBTBADOPT\fR, these +errors will alternatively be returned by \fBt_rcvuderr\fR(3NSL). An +application must therefore be prepared to receive these errors in both of these +ways. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a value +of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADADDR\fR\fR +.ad +.RS 15n +.rt +The specified protocol address was in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADDATA\fR\fR +.ad +.RS 15n +.rt +Illegal amount of data. +.RS +4 +.TP +.ie t \(bu +.el o +A single send was attempted specifying a TSDU greater than that specified in +the \fIinfo\fR argument, or a send of a zero byte TSDU is not supported by the +provider. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fIiovcount\fR is greater than \fBT_IOV_MAX.\fR +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 15n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTBADOPT\fR\fR +.ad +.RS 15n +.rt +The specified options were in an incorrect format or contained illegal +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTFLOW\fR\fR +.ad +.RS 15n +.rt +\fBO_NONBLOCK\fR \fBi\fR was set, but the flow control mechanism prevented the +transport provider from accepting any data at this time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 15n +.rt +An asynchronous event has occurred on this transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTNOTSUPPORT\fR\fR +.ad +.RS 15n +.rt +This function is not supported by the underlying transport provider. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 15n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 15n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 15n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBt_alloc\fR(3NSL), \fBt_open\fR(3NSL), +\fBt_rcvudata\fR(3NSL), \fBt_rcvvudata\fR(3NSL) \fBt_rcvuderr\fR(3NSL), +\fBt_sndudata\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_strerror.3nsl b/usr/src/man/man3nsl/t_strerror.3nsl new file mode 100644 index 0000000000..2f140798a5 --- /dev/null +++ b/usr/src/man/man3nsl/t_strerror.3nsl @@ -0,0 +1,101 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_strerror 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_strerror \- produce an error message string +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + + +\fBconst char *\fR\fBt_strerror\fR(\fBint\fR \fIerrnum\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +The \fBt_strerror()\fR function maps the error number in \fIerrnum\fR that +corresponds to an XTI error to a language-dependent error message string and +returns a pointer to the string. The string pointed to will not be modified by +the program, but may be overwritten by a subsequent call to the +\fIt_strerror\fR function. The string is not terminated by a newline character. +The language for error message strings written by \fBt_strerror()\fR is that of +the current locale. If it is English, the error message string describing the +value in \fBt_errno\fR may be derived from the comments following the +\fBt_errno\fR codes defined in \fB<xti.h>\fR\&. If an error code is unknown, +and the language is English, \fBt_strerror()\fR returns the string: +.sp +.in +2 +.nf +"<error>: error unknown" +.fi +.in -2 + +.sp +.LP +where <error> is the error number supplied as input. In other languages, an +equivalent text is provided. +.SH VALID STATES +.sp +.LP +ALL - apart from \fBT_UNINIT\fR. +.SH RETURN VALUES +.sp +.LP +The function \fBt_strerror()\fR returns a pointer to the generated message +string. +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_errno\fR(3NSL),\fBt_error\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_sync.3nsl b/usr/src/man/man3nsl/t_sync.3nsl new file mode 100644 index 0000000000..0e08e040ce --- /dev/null +++ b/usr/src/man/man3nsl/t_sync.3nsl @@ -0,0 +1,243 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sync 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sync \- synchronize transport library +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_sync\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +For the transport endpoint specified by \fIfd\fR, \fBt_sync()\fR synchronizes +the data structures managed by the transport library with information from the +underlying transport provider. In doing so, it can convert an uninitialized +file descriptor (obtained by means of a \fBopen\fR(2), \fBdup\fR(2) or as a +result of a \fBfork\fR(2) and \fBexec\fR(2)) to an initialized transport +endpoint, assuming that the file descriptor referenced a transport endpoint, +by updating and allocating the necessary library data structures. This function +also allows two cooperating processes to synchronize their interaction with a +transport provider. +.sp +.LP +For example, if a process forks a new process and issues an \fBexec\fR(2), the +new process must issue a \fBt_sync()\fR to build the private library data +structure associated with a transport endpoint and to synchronize the data +structure with the relevant provider information. +.sp +.LP +It is important to remember that the transport provider treats all users of a +transport endpoint as a single user. If multiple processes are using the same +endpoint, they should coordinate their activities so as not to violate the +state of the transport endpoint. The function \fBt_sync()\fR returns the +current state of the transport endpoint to the user, thereby enabling the user +to verify the state before taking further action. This coordination is only +valid among cooperating processes; it is possible that a process or an incoming +event could change the endpoint's state \fIafter\fR a \fBt_sync()\fR is issued. +.sp +.LP +If the transport endpoint is undergoing a state transition when \fBt_sync()\fR +is called, the function will fail. +.SH RETURN VALUES +.sp +.LP +On successful completion, the state of the transport endpoint is returned. +Otherwise, a value of -1 is returned and \fBt_errno\fR is set to indicate an +error. The state returned is one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBT_UNBND\fR \fR +.ad +.RS 15n +.rt +Unbound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_IDLE\fR \fR +.ad +.RS 15n +.rt +Idle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OUTCON\fR \fR +.ad +.RS 15n +.rt +Outgoing connection pending. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_INCON\fR \fR +.ad +.RS 15n +.rt +Incoming connection pending. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_DATAXFER\fR \fR +.ad +.RS 15n +.rt +Data transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_OUTREL\fR \fR +.ad +.RS 15n +.rt +Outgoing orderly release (waiting for an orderly release indication). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBT_INREL\fR \fR +.ad +.RS 15n +.rt +Incoming orderly release (waiting for an orderly release request). +.RE + +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 14n +.rt +The specified file descriptor does not refer to a transport endpoint. This +error may be returned when the \fIfd\fR has been previously closed or an +erroneous number may have been passed to the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 14n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSTATECHNG\fR\fR +.ad +.RS 14n +.rt +The transport endpoint is undergoing a state change. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 14n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR. \fBTLI\fR interfaces +should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdup\fR(2), \fBexec\fR(2), \fBfork\fR(2), \fBopen\fR(2), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_sysconf.3nsl b/usr/src/man/man3nsl/t_sysconf.3nsl new file mode 100644 index 0000000000..0ee464f063 --- /dev/null +++ b/usr/src/man/man3nsl/t_sysconf.3nsl @@ -0,0 +1,101 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_sysconf 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_sysconf \- get configurable XTI variables +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_sysconf\fR(\fBint\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBt_sysconf()\fR function provides a method for the application to +determine the current value of configurable and implementation-dependent XTI +limits or options. +.sp +.LP +The \fIname\fR argument represents the XTI system variable to be queried. The +following table lists the minimal set of XTI system variables from +\fB<xti.h>\fR that can be returned by \fBt_sysconf()\fR, and the symbolic +constants, defined in \fB<xti.h>\fR that are the corresponding values used for +\fIname\fR. +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +VariableValue of Name +_ +T_IOV_MAX_SC_T_IOV_MAX +.TE + +.SH RETURN VALUES +.sp +.LP +If \fIname\fR is valid, \fBt_sysconf()\fR returns the value of the requested +limit/option, which might be -1, and leaves \fBt_errno\fR unchanged. +Otherwise, a value of -1 is returned and \fBt_errno\fR is set to indicate an +error. +.SH VALID STATES +.sp +.LP +All. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADFLAG\fR\fR +.ad +.RS 12n +.rt +\fIname\fR has an invalid value. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +In the \fBTLI\fR interface definition, no counterpart of this routine was +defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsysconf\fR(3C), \fBt_rcvv\fR(3NSL), \fBt_rcvvudata\fR(3NSL), +\fBt_sndv\fR(3NSL), \fBt_sndvudata\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/t_unbind.3nsl b/usr/src/man/man3nsl/t_unbind.3nsl new file mode 100644 index 0000000000..e72c423a5e --- /dev/null +++ b/usr/src/man/man3nsl/t_unbind.3nsl @@ -0,0 +1,155 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH t_unbind 3NSL "7 May 1998" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +t_unbind \- disable a transport endpoint +.SH SYNOPSIS +.LP +.nf +#include <xti.h> + + + +\fBint\fR \fBt_unbind\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The This routine is part of the \fBXTI\fR interfaces which evolved from the +\fBTLI\fR interfaces. \fBXTI\fR represents the future evolution of these +interfaces. However, \fBTLI\fR interfaces are supported for compatibility. When +using a \fBTLI\fR routine that has the same name as an \fBXTI\fR routine, the +\fBtiuser.h\fR header file must be used. Refer to the \fBTLI\fR +\fBCOMPATIBILITY\fR section for a description of differences between the two +interfaces. +.sp +.LP +\fBt_unbind()\fR function disables the transport endpoint specified by \fIfd\fR +which was previously bound by \fBt_bind\fR(3NSL). On completion of this call, +no further data or events destined for this transport endpoint will be accepted +by the transport provider. An endpoint which is disabled by using +\fBt_unbind()\fR can be enabled by a subsequent call to \fBt_bind\fR(3NSL). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a value of \fB0\fR is returned. Otherwise, a +value of -1 is returned and \fBt_errno\fR is set to indicate an error. +.SH VALID STATES +.sp +.LP +\fBT_IDLE\fR. +.SH ERRORS +.sp +.LP +On failure, \fBt_errno\fR is set to one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTBADF\fR\fR +.ad +.RS 13n +.rt +The specified file descriptor does not refer to a transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTLOOK\fR\fR +.ad +.RS 13n +.rt +An asynchronous event has occurred on this transport endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTOUTSTATE\fR\fR +.ad +.RS 13n +.rt +The communications endpoint referenced by \fIfd\fR is not in one of the states +in which a call to this function is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTPROTO\fR\fR +.ad +.RS 13n +.rt +This error indicates that a communication problem has been detected between XTI +and the transport provider for which there is no other suitable XTI error +\fB(t_errno)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTSYSERR\fR\fR +.ad +.RS 13n +.rt +A system error has occurred during execution of this function. +.RE + +.SH TLI COMPATIBILITY +.sp +.LP +The \fBXTI\fR and \fBTLI\fR interface definitions have common names but use +different header files. This, and other semantic differences between the two +interfaces are described in the subsections below. +.SS "Interface Header" +.sp +.LP +The \fBXTI\fR interfaces use the header file, \fBxti.h\fR \fB\&.\fR \fBTLI\fR +interfaces should \fInot\fR use this header. They should use the header: +.br +.in +2 +#include <tiuser.h> +.in -2 +.SS "Error Description Values" +.sp +.LP +The \fBt_errno\fR value that can be set by the \fBXTI\fR interface and cannot +be set by the \fBTLI\fR interface is: +.br +.in +2 +\fBTPROTO\fR +.in -2 +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBt_bind\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/xdr.3nsl b/usr/src/man/man3nsl/xdr.3nsl new file mode 100644 index 0000000000..b10e989964 --- /dev/null +++ b/usr/src/man/man3nsl/xdr.3nsl @@ -0,0 +1,503 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH xdr 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +xdr \- library routines for external data representation +.SH DESCRIPTION +.sp +.LP +\fBXDR\fR routines allow C programmers to describe arbitrary data structures in +a machine-independent fashion. Data for remote procedure calls (RPC) are +transmitted using these routines. +.SS "Index to Routines" +.sp +.LP +The following table lists \fBXDR\fR routines and the manual reference pages on +which they are described: +.sp +.ne 2 +.mk +.na +\fB\fBXDR Routine\fR\fR +.ad +.RS 22n +.rt + \fBManual Reference Page\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_array\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_bool\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_bytes\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_char\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_control\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_destroy\fR\fR +.ad +.RS 22n +.rt +\fBxdr_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_double\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_enum\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_float\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_free\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_getpos\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_hyper\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_inline\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_int\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_long\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_longlong_t\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_opaque\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_pointer\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_quadruple\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_reference\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_setpos\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_short\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_sizeof\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_string\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_char\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_hyper\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_int\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_long\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_longlong_t\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_short\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_union\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_vector\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_void\fR\fR +.ad +.RS 22n +.rt +\fBxdr_simple\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_wrapstring\fR\fR +.ad +.RS 22n +.rt +\fBxdr_complex\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrmem_create\fR\fR +.ad +.RS 22n +.rt +\fBxdr_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrrec_create\fR\fR +.ad +.RS 22n +.rt +\fBxdr_create\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrrec_endofrecord\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrrec_eof\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrrec_readbytes\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrrec_skiprecord\fR\fR +.ad +.RS 22n +.rt +\fBxdr_admin\fR(3NSL) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrstdio_create\fR\fR +.ad +.RS 22n +.rt +\fBxdr_create\fR(3NSL) +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL), \fBxdr_complex\fR(3NSL), +\fBxdr_create\fR(3NSL), \fBxdr_simple\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/xdr_admin.3nsl b/usr/src/man/man3nsl/xdr_admin.3nsl new file mode 100644 index 0000000000..66c241687f --- /dev/null +++ b/usr/src/man/man3nsl/xdr_admin.3nsl @@ -0,0 +1,200 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH xdr_admin 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +xdr_admin, xdr_control, xdr_getpos, xdr_inline, xdrrec_endofrecord, xdrrec_eof, +xdrrec_readbytes, xdrrec_skiprecord, xdr_setpos, xdr_sizeof \- library routines +for external data representation +.SH DESCRIPTION +.sp +.LP +\fBXDR\fR library routines allow C programmers to describe arbitrary data +structures in a machine-independent fashion. Protocols such as remote procedure +calls (RPC) use these routines to describe the format of the data. +.sp +.LP +These routines deal specifically with the management of the \fBXDR\fR stream. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. Note +that any buffers passed to the \fBXDR\fR routines must be properly aligned. It +is suggested either that \fBmalloc\fR(3C) be used to allocate these buffers, or +that the programmer insure that the buffer address is divisible evenly by +four. +.sp +.LP +\fB#include <rpc/xdr.h>\fR +.sp +.ne 2 +.mk +.na +\fB\fBbool_t xdr_control( XDR *\fR\fIxdrs\fR\fB, int\fR\fI req\fR\fB, void +*\fR\fIinfo\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +A function macro to change or retrieve various information about an \fBXDR\fR +stream. \fIreq\fR indicates the type of operation and \fIinfo\fR is a pointer +to the information. The supported values of \fIreq\fR is +\fBXDR_GET_BYTES_AVAIL\fR and its argument type is \fBxdr_bytesrec *\fR. They +return the number of bytes left unconsumed in the stream and a flag indicating +whether or not this is the last fragment. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuint_t xdr_getpos(const XDR *\fR\fIxdrs\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +A macro that invokes the get-position routine associated with the \fBXDR\fR +stream, \fIxdrs\fR. The routine returns an unsigned integer, which indicates +the position of the \fBXDR\fR byte stream. A desirable feature of \fBXDR\fR +streams is that simple arithmetic works with this number, although the +\fBXDR\fR stream instances need not guarantee this. Therefore, applications +written for portability should not depend on this feature. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBlong *xdr_inline(XDR *\fR\fIxdrs\fR\fB, const int \fR\fIlen\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +A macro that invokes the in-line routine associated with the \fBXDR\fR stream, +\fIxdrs\fR. The routine returns a pointer to a contiguous piece of the stream's +buffer; \fIlen\fR is the byte length of the desired buffer. Note: pointer is +cast to \fBlong *\fR. +.sp +Warning: \fBxdr_inline()\fR may return \fINULL\fR (\fB0\fR) if it cannot +allocate a contiguous piece of a buffer. Therefore the behavior may vary among +stream instances; it exists for the sake of efficiency, and applications +written for portability should not depend on this feature. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbool_t xdrrec_endofrecord(XDR *xdrs, int \fR\fIsendnow\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +This routine can be invoked only on streams created by \fBxdrrec_create()\fR. +See \fBxdr_create\fR(3NSL). The data in the output buffer is marked as a +completed record, and the output buffer is optionally written out if +\fIsendnow\fR is non-zero. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbool_t xdrrec_eof(XDR *\fR\fIxdrs\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +This routine can be invoked only on streams created by \fBxdrrec_create()\fR. +After consuming the rest of the current record in the stream, this routine +returns \fBTRUE\fR if there is no more data in the stream's input buffer. It +returns \fBFALSE\fR if there is additional data in the stream's input buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBint xdrrec_readbytes(XDR *\fR\fIxdrs\fR\fB, caddr_t\fR\fI addr\fR\fB, +uint_t\fR\fI nbytes\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +This routine can be invoked only on streams created by \fBxdrrec_create()\fR. +It attempts to read \fInbytes\fR bytes from the \fBXDR\fR stream into the +buffer pointed to by \fIaddr\fR. Upon success this routine returns the number +of bytes read. Upon failure, it returns \fB\(mi1\fR\&. A return value of +\fB0\fR indicates an end of record. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbool_t xdrrec_skiprecord(XDR *\fR\fIxdrs\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +This routine can be invoked only on streams created by \fBxdrrec_create()\fR. +See \fBxdr_create\fR(3NSL). It tells the \fBXDR\fR implementation that the +rest of the current record in the stream's input buffer should be discarded. +This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbool_t xdr_setpos(XDR *\fR\fIxdrs\fR\fB, const uint_t +\fR\fIpos\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +A macro that invokes the set position routine associated with the \fBXDR\fR +stream \fIxdrs\fR. The parameter \fIpos\fR is a position value obtained from +\fBxdr_getpos()\fR. This routine returns \fBTRUE\fR if the \fBXDR\fR stream was +repositioned, and \fBFALSE\fR otherwise. +.sp +Warning: it is difficult to reposition some types of \fBXDR\fR streams, so this +routine may fail with one type of stream and succeed with another. Therefore, +applications written for portability should not depend on this feature. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBunsigned long xdr_sizeof(xdrproc_t \fR\fIfunc\fR\fB, void +*\fR\fIdata\fR\fB);\fR\fR +.ad +.sp .6 +.RS 4n +This routine returns the number of bytes required to encode \fIdata\fR using +the \fBXDR\fR filter function \fIfunc\fR, excluding potential overhead such as +\fBRPC\fR headers or record markers. \fB0\fR is returned on error. This +information might be used to select between transport protocols, or to +determine the buffer size for various lower levels of \fBRPC\fR client and +server creation routines, or to allocate storage when \fBXDR\fR is used +outside of the \fBRPC\fR subsystem. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_complex\fR(3NSL), +\fBxdr_create\fR(3NSL), \fBxdr_simple\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/xdr_complex.3nsl b/usr/src/man/man3nsl/xdr_complex.3nsl new file mode 100644 index 0000000000..5a2b0869ca --- /dev/null +++ b/usr/src/man/man3nsl/xdr_complex.3nsl @@ -0,0 +1,221 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH xdr_complex 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +xdr_complex, xdr_array, xdr_bytes, xdr_opaque, xdr_pointer, xdr_reference, +xdr_string, xdr_union, xdr_vector, xdr_wrapstring \- library routines for +external data representation +.SH DESCRIPTION +.sp +.LP +\fBXDR\fR library routines allow C programmers to describe complex data +structures in a machine-independent fashion. Protocols such as remote procedure +calls (RPC) use these routines to describe the format of the data. These +routines are the \fBXDR\fR library routines for complex data structures. They +require the creation of \fBXDR\fR streams. See \fBxdr_create\fR(3NSL). +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. Note +that any buffers passed to the \fBXDR\fR routines must be properly aligned. It +is suggested either that \fBmalloc()\fR be used to allocate these buffers, or +that the programmer insure that the buffer address is divisible evenly by +four. +.sp +.LP +\fB#include <rpc/xdr.h>\fR +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_array(XDR *\fIxdrs\fR, caddr_t *\fIarrp\fR, uint_t *\fIsizep\fR, +const uint_t \fImaxsize\fR, const uint_t \fIelsize\fR, const xdrproc_t +\fIelproc\fR);\fR +.ad +.sp .6 +.RS 4n +\fBxdr_array()\fR translates between variable-length arrays and their +corresponding external representations. The parameter \fIarrp\fR is the address +of the pointer to the array, while \fIsizep\fR is the address of the element +count of the array; this element count cannot exceed \fImaxsize\fR. The +parameter \fIelsize\fR is the size of each of the array's elements, and +\fIelproc\fR is an \fBXDR\fR routine that translates between the array +elements' C form and their external representation. If \fB*\fR\fIaarp\fR is +\fINULL\fR when decoding, \fB xdr_array()\fR allocates memory and +\fB*\fR\fIaarp\fR points to it. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_bytes(XDR *\fIxdrs\fR, char **\fIsp\fR, uint_t *\fIsizep\fR, +const uint_t \fImaxsize\fR);\fR +.ad +.sp .6 +.RS 4n +\fBxdr_bytes()\fR translates between counted byte strings and their external +representations. The parameter \fIsp\fR is the address of the string pointer. +The length of the string is located at address \fIsizep\fR; strings cannot be +longer than \fImaxsize\fR. If \fB*\fR\fIsp\fR is \fINULL\fR when decoding, +\fBxdr_bytes()\fR allocates memory and \fB*\fR\fIsp\fR points to it. This +routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_opaque(XDR *\fIxdrs\fR, caddr_t \fIcp\fR, const uint_t +\fIcnt\fR);\fR +.ad +.sp .6 +.RS 4n +\fBxdr_opaque()\fR translates between fixed size opaque data and its external +representation. The parameter \fBcp\fR is the address of the opaque object, and +\fIcnt\fR is its size in bytes. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_pointer(XDR *\fIxdrs\fR, char **objpp, uint_t \fIobjsize\fR, +const xdrproc_t \fIxdrobj\fR);\fR +.ad +.sp .6 +.RS 4n +Like \fBxdr_reference()\fR except that it serializes null pointers, whereas +\fBxdr_reference()\fR does not. Thus, \fBxdr_pointer()\fR can represent +recursive data structures, such as binary trees or linked lists. If +\fB*\fR\fIobjpp\fR is \fINULL\fR when decoding, \fBxdr_pointer()\fR allocates +memory and \fB*\fR\fIobjpp\fR points to it. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_reference(XDR *\fIxdrs\fR, caddr_t *\fIpp\fR, uint_t \fIsize\fR, +const xdrproc_t \fIproc\fR);\fR +.ad +.sp .6 +.RS 4n +\fBxdr_reference()\fR provides pointer chasing within structures. The +parameter \fIpp\fR is the address of the pointer; \fBsize\fR is the +\fBsizeof\fR the structure that \fI*pp\fR points to; and \fBproc\fR is an +\fBXDR\fR procedure that translates the structure between its C form and its +external representation. If \fB*\fR\fIpp\fR is \fINULL\fR when decoding, +\fBxdr_reference()\fR allocates memory and \fB*\fR\fIpp\fR points to it. This +routine returns \fB1\fR if it succeeds, \fB0\fR otherwise. +.sp +Warning: this routine does not understand null pointers. Use +\fBxdr_pointer()\fR instead. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_string(XDR *\fIxdrs\fR, char **\fIsp\fR, const uint_t +\fImaxsize\fR);\fR +.ad +.sp .6 +.RS 4n +\fBxdr_string()\fR translates between C strings and their corresponding +external representations. Strings cannot be longer than \fImaxsize\fR. Note: +\fIsp\fR is the address of the string's pointer. If \fB*\fR\fIsp\fR is +\fINULL\fR when decoding, \fBxdr_string()\fR allocates memory and +\fB*\fR\fIsp\fR points to it. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. Note: \fBxdr_string()\fR can be used to send an empty +string ("\|"), but not a null string. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_union(XDR *\fIxdrs\fR, enum_t *\fIdscmp\fR, char *\fIunp\fR, +const struct xdr_discrim *\fIchoices\fR, const xdrproc_t +(*\fIdefaultarm\fR));\fR +.ad +.sp .6 +.RS 4n +\fBxdr_union()\fR translates between a discriminated C \fBunion\fR and its +corresponding external representation. It first translates the discriminant of +the union located at \fIdscmp\fR. This discriminant is always an \fBenum_t\fR. +Next the union located at \fIunp\fR is translated. The parameter \fIchoices\fR +is a pointer to an array of \fBxdr_discrim\fR structures. Each structure +contains an ordered pair of [\fIvalue, proc\fR]. If the union's discriminant is +equal to the associated \fIvalue\fR, then the \fBproc\fR is called to translate +the union. The end of the \fBxdr_discrim\fR structure array is denoted by a +routine of value \fINULL\fR. If the discriminant is not found in the +\fIchoices\fR array, then the \fIdefaultarm\fR procedure is called (if it is +not \fINULL\fR). It returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_vector(XDR *\fIxdrs\fR, char *\fIarrp\fR, const uint_t +\fIsize\fR, const uint_t \fIelsize\fR, const xdrproc_t \fIelproc\fR);\fR +.ad +.sp .6 +.RS 4n +\fBxdr_vector()\fR translates between fixed-length arrays and their +corresponding external representations. The parameter \fIarrp\fR is the address +of the pointer to the array, while \fBsize\fR is the element count of the +array. The parameter \fIelsize\fR is the \fBsizeof\fR each of the array's +elements, and \fIelproc\fR is an \fBXDR\fR routine that translates between the +array elements' C form and their external representation. This routine returns +\fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fBbool_t xdr_wrapstring(XDR *\fIxdrs\fR, char **\fIsp\fR);\fR +.ad +.sp .6 +.RS 4n +A routine that calls \fBxdr_string(\fR\fIxdrs\fR\fB,\fR \fIsp\fR\fB, +\fR\fImaxuint\fR\fB);\fR where \fImaxuint\fR is the maximum value of an +unsigned integer. +.sp +Many routines, such as \fBxdr_array()\fR, \fBxdr_pointer()\fR, and +\fBxdr_vector()\fR take a function pointer of type \fBxdrproc_t()\fR, which +takes two arguments. \fBxdr_string()\fR, one of the most frequently used +routines, requires three arguments, while \fBxdr_wrapstring()\fR only requires +two. For these routines, \fBxdr_wrapstring()\fR is desirable. This routine +returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL), +\fBxdr_create\fR(3NSL), \fBxdr_simple\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/xdr_create.3nsl b/usr/src/man/man3nsl/xdr_create.3nsl new file mode 100644 index 0000000000..95a848b928 --- /dev/null +++ b/usr/src/man/man3nsl/xdr_create.3nsl @@ -0,0 +1,157 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH xdr_create 3NSL "26 Sep 2000" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +xdr_create, xdr_destroy, xdrmem_create, xdrrec_create, xdrstdio_create \- +library routines for external data representation stream creation +.SH SYNOPSIS +.LP +.nf +#include <rpc/xdr.h> + +\fBvoid\fR \fBxdr_destroy\fR(\fBXDR *\fR\fIxdrs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBxdrmem_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst caddr_t\fR \fIaddr\fR, \fBconst uint_t\fR \fIsize\fR, + \fBconst enum xdr_op\fR \fIop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBxdrrec_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst uint_t\fR \fIsendsz\fR, \fBconst uint_t\fR \fIrecvsz\fR, + \fBconst caddr_t\fR \fIhandle\fR, \fBconst int (*\fR\fIreadit\fR)const void *\fIread_handle\fR, + char *\fIbuf\fR, const int \fIlen\fR, \fBconst int (*\fR\fIwriteit\fR) + const void *\fIwrite_handle\fR, const char *\fIbuf\fR, const int \fIlen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBxdrstdio_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBFILE *\fR + \fIfile\fR, \fBconst enum xdr_op\fR \fIop\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBXDR\fR library routines allow C programmers to describe arbitrary data +structures in a machine-independent fashion. Protocols such as remote procedure +calls (RPC) use these routines to describe the format of the data. +.sp +.LP +These routines deal with the creation of \fBXDR\fR streams, which must be +created before any data can be translated into \fBXDR\fR format. +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR \fBCLIENT\fR and +\fBSVCXPRT\fR data structures. Any buffers passed to the \fBXDR\fR routines +must be properly aligned. Use \fBmalloc\fR(3C) to allocate these buffers or be +sure that the buffer address is divisible evenly by four. +.sp +.ne 2 +.mk +.na +\fB\fBxdr_destroy()\fR\fR +.ad +.RS 21n +.rt +A macro that invokes the destroy routine associated with the \fBXDR\fR stream, +\fIxdrs\fR. Private data structures associated with the stream are freed. +Using \fIxdrs\fR after \fBxdr_destroy()\fR is invoked is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrmem_create()\fR\fR +.ad +.RS 21n +.rt +This routine initializes the \fBXDR\fR stream object pointed to by \fIxdrs\fR. +The stream's data is written to or read from a chunk of memory at location +\fIaddr\fR whose length is no less than \fIsize\fR bytes long. The \fIop\fR +determines the direction of the \fBXDR\fR stream. The value of \fIop\fR can be +either \fBXDR_ENCODE\fR, \fBXDR_DECODE\fR, or \fBXDR_FREE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrrec_create()\fR\fR +.ad +.RS 21n +.rt +This routine initializes the read-oriented \fBXDR\fR stream object pointed to +by \fIxdrs\fR. The stream's data is written to a buffer of size \fIsendsz\fR. A +value of \fB0\fR indicates the system should use a suitable default. The +stream's data is read from a buffer of size \fIrecvsz\fR. It too can be set to +a suitable default by passing a \fB0\fR value. When a stream's output buffer +is full, \fIwriteit\fR is called. Similarly, when a stream's input buffer is +empty, \fBxdrrec_create()\fR calls \fIreadit\fR. The behavior of these two +routines is similar to the system calls \fBread()\fR and \fBwrite()\fR, except +that an appropriate handle, \fIread_handle\fR or \fIwrite_handle\fR, is passed +to the former routines as the first parameter instead of a file descriptor. See +\fBread\fR(2) and \fBwrite\fR(2), respectively. The \fBXDR\fR stream's \fIop\fR +field must be set by the caller. +.sp +This \fBXDR\fR stream implements an intermediate record stream. Therefore, +additional bytes in the stream are provided for record boundary information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdrstdio_create()\fR\fR +.ad +.RS 21n +.rt +This routine initializes the \fBXDR\fR stream object pointed to by \fIxdrs\fR. +The \fBXDR\fR stream data is written to or read from the standard \fBI/O\fR +stream \fBfile\fR. The parameter \fIop\fR determines the direction of the +\fBXDR\fR stream. The value of \fIop\fR can be either \fBXDR_ENCODE\fR, +\fBXDR_DECODE\fR, or \fBXDR_FREE\fR. +.sp +The destroy routine associated with \fBXDR\fR streams calls \fBfflush()\fR on +the \fIfile\fR stream, but never \fBfclose()\fR. See \fBfclose\fR(3C). +.RE + +.sp +.LP +A failure of any of these functions can be detected by first initializing the +\fIx_ops\fR field in the \fBXDR\fR structure (\fIxdrs\fR-> \fIx_ops\fR) to +\fINULL\fR before calling the \fBxdr*_create()\fR function. If the +\fIx_ops\fR field is still \fINULL,\fR after the return from the +\fBxdr*_create()\fR function, the call has failed. If the \fIx_ops\fR field +contains some other value, assume that the call has succeeded. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBwrite\fR(2), \fBfclose\fR(3C), \fBmalloc\fR(3C), +\fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL), \fBxdr_complex\fR(3NSL), +\fBxdr_simple\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/xdr_simple.3nsl b/usr/src/man/man3nsl/xdr_simple.3nsl new file mode 100644 index 0000000000..df87758808 --- /dev/null +++ b/usr/src/man/man3nsl/xdr_simple.3nsl @@ -0,0 +1,410 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH xdr_simple 3NSL "27 Aug 2001" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +xdr_simple, xdr_bool, xdr_char, xdr_double, xdr_enum, xdr_float, xdr_free, +xdr_hyper, xdr_int, xdr_long, xdr_longlong_t, xdr_quadruple, xdr_short, +xdr_u_char, xdr_u_hyper, xdr_u_int, xdr_u_long, xdr_u_longlong_t, xdr_u_short, +xdr_void \- library routines for external data representation +.SH SYNOPSIS +.LP +.nf +#include<rpc/xdr.h> + + + +\fBbool_t\fR \fBxdr_bool\fR(\fBXDR *\fR\fIxdrs\fR, \fBbool_t *\fR\fIbp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_char\fR(\fBXDR *\fR\fIxdrs\fR, \fBchar *\fR\fIcp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_double\fR(\fBXDR *\fR\fIxdrs\fR, \fBdouble *\fR\fIdp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_enum\fR(\fBXDR *\fR\fIxdrs\fR, \fBenum_t *\fR\fIep\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_float\fR(\fBXDR *\fR\fIxdrs\fR, \fBfloat *\fR\fIfp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBxdr_free\fR(\fBxdrproc_t\fR \fIproc\fR, \fBchar *\fR\fIobjp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_hyper\fR(\fBXDR *\fR\fIxdrs\fR, \fBlonglong_t *\fR\fIllp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_int\fR(\fBXDR *\fR\fIxdrs\fR, \fBint *\fR\fIip\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_long\fR(\fBXDR *\fR\fIxdrs\fR, \fBlongt *\fR\fIlp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_longlong_t\fR(\fBXDR *\fR\fIxdrs\fR, \fBlonglong_t *\fR\fIllp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_quadruple\fR(\fBXDR *\fR\fIxdrs\fR, \fBlong double *\fR\fIpq\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_short\fR(\fBXDR *\fR\fIxdrs\fR, \fBshort *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_u_char\fR(\fBXDR *\fR\fIxdrs\fR, \fBunsigned char *\fR\fIucp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_u_hyper\fR(\fBXDR *\fR\fIxdrs\fR, \fBu_longlong_t *\fR\fIullp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_u_int\fR(\fBXDR *\fR\fIxdrs\fR, \fBunsigned *\fR\fIup\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_u_long\fR(\fBXDR *\fR\fIxdrs\fR, \fBunsigned long *\fR\fIulp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_u_longlong_t\fR(\fBXDR *\fR\fIxdrs\fR, \fBu_longlong_t *\fR\fIullp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_u_short\fR(\fBXDR\fR \fIxdrs\fR, \fBunsigned short *\fR\fIusp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_void\fR(void) +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBXDR\fR library routines allow C programmers to describe simple data +structures in a machine-independent fashion. Protocols such as remote procedure +calls (RPC) use these routines to describe the format of the data. +.sp +.LP +These routines require the creation of \fBXDR\fR streams (see +\fBxdr_create\fR(3NSL)). +.SS "Routines" +.sp +.LP +See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. Note +that any buffers passed to the \fBXDR\fR routines must be properly aligned. It +is suggested that \fBmalloc\fR(3C) be used to allocate these buffers or that +the programmer insure that the buffer address is divisible evenly by four. +.sp +.ne 2 +.mk +.na +\fB\fBxdr_bool()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_bool()\fR translates between booleans (C integers) and their external +representations. When encoding data, this filter produces values of either +\fB1\fR or \fB0\fR. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_char()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_char()\fR translates between C characters and their external +representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to consider \fBxdr_bytes()\fR, +\fBxdr_opaque()\fR, or \fBxdr_string()\fR (see \fBxdr_complex\fR(3NSL)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_double()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_double()\fR translates between C \fBdouble\fR precision numbers and +their external representations. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_enum()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_enum()\fR translates between C \fBenum\fRs (actually integers) and their +external representations. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_float()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_float()\fR translates between C \fBfloat\fRs and their external +representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_free()\fR\fR +.ad +.RS 22n +.rt +Generic freeing routine. The first argument is the \fBXDR\fR routine for the +object being freed. The second argument is a pointer to the object itself. +Note: the pointer passed to this routine is not freed, but what it points to is +freed (recursively, depending on the XDR routine). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_hyper()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_hyper()\fR translates between ANSI C \fBlong\fR \fBlong\fR integers and +their external representations. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_int()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_int()\fR translates between C integers and their external +representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_long()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_long()\fR translates between C \fBlong\fR integers and their external +representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. +.sp +In a 64-bit environment, this routine returns an error if the value of \fBlp\fR +is outside the range \fB[INT32_MIN, INT32_MAX]\fR. The \fBxdr_int()\fR routine +is recommended in place of this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_longlong_t()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_longlong_t()\fR translates between ANSI C \fBlong\fR \fBlong\fR +integers and their external representations. This routine returns \fBTRUE\fR if +it succeeds, \fBFALSE\fR otherwise. This routine is identical to +\fBxdr_hyper()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_quadruple()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_quadruple()\fR translates between IEEE quadruple precision floating +point numbers and their external representations. This routine returns +\fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_short()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_short()\fR translates between C \fBshort\fR integers and their external +representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR +otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_char()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_u_char()\fR translates between \fBunsigned\fR C characters and their +external representations. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_hyper()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_u_hyper()\fR translates between unsigned ANSI C \fBlong\fR \fBlong\fR +integers and their external representations. This routine returns \fBTRUE\fR if +it succeeds, \fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_int()\fR\fR +.ad +.RS 22n +.rt +A filter primitive that translates between a C \fBunsigned\fR integer and its +external representation. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_long()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_u_long()\fR translates between C \fBunsigned long\fR integers and their +external representations. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.sp +In a 64-bit environment, this routine returns an error if the value of +\fIulp\fR is outside the range \fB[0, UINT32_MAX]\fR. The \fBxdr_u_int()\fR +routine is recommended in place of this routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_longlong_t()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_u_longlong_t()\fR translates between unsigned ANSI C \fBlong\fR +\fBlong\fR integers and their external representations. This routine returns +\fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. This routine is identical to +\fBxdr_u_hyper()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_u_short()\fR\fR +.ad +.RS 22n +.rt +\fBxdr_u_short()\fR translates between C \fBunsigned short\fR integers and +their external representations. This routine returns \fBTRUE\fR if it succeeds, +\fBFALSE\fR otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxdr_void()\fR\fR +.ad +.RS 22n +.rt +This routine always returns \fBTRUE\fR. It may be passed to \fBRPC\fR routines +that require a function parameter, where nothing is to be done. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL), +\fBxdr_complex\fR(3NSL), \fBxdr_create\fR(3NSL), \fBattributes\fR(5) diff --git a/usr/src/man/man3nsl/yp_update.3nsl b/usr/src/man/man3nsl/yp_update.3nsl new file mode 100644 index 0000000000..209764a359 --- /dev/null +++ b/usr/src/man/man3nsl/yp_update.3nsl @@ -0,0 +1,72 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH yp_update 3NSL "30 Dec 1996" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +yp_update \- change NIS information +.SH SYNOPSIS +.LP +.nf +#include <rpcsvc/ypclnt.h> + + + +\fBint\fR \fByp_update\fR(\fBchar *\fR\fIdomain\fR, \fBchar *\fR\fImap\fR, \fBunsigned\fR \fIypop\fR, \fBchar *\fR\fIkey\fR, + \fBchar *\fR\fBint\fR \fIkeylen\fR, \fBchar *\fR\fIdata\fR, \fBint\fR \fIdatalen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fByp_update()\fR is used to make changes to the NIS database. The syntax is +the same as that of \fByp_match()\fR except for the extra parameter \fIypop\fR +which may take on one of four values. If it is \fBPOP_CHANGE\fR then the data +associated with the key will be changed to the new value. If the key is not +found in the database, then \fByp_update()\fR will return \fBYPERR_KEY\fR. If +\fIypop\fR has the value \fBYPOP_INSERT\fR then the key-value pair will be +inserted into the database. The error \fBYPERR_KEY\fR is returned if the key +already exists in the database. To store an item into the database without +concern for whether it exists already or not, pass \fIypop\fR as +\fBYPOP_STORE\fR and no error will be returned if the key already or does not +exist. To delete an entry, the value of \fIypop\fR should be \fBYPOP_DELETE\fR. +.sp +.LP +This routine depends upon secure \fBRPC,\fR and will not work unless the +network is running secure \fBRPC.\fR +.SH RETURN VALUES +.sp +.LP +If the value of \fIypop\fR is \fBPOP_CHANGE,\fR \fByp_update()\fR returns the +error \fBYPERR_KEY\fR if the key is not found in the database. +.sp +.LP +If the value of \fIypop\fR is \fBPOP_INSERT,\fR \fByp_update()\fR returns the +error \fBYPERR_KEY\fR if the key already exists in the database. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsecure_rpc\fR(3NSL), \fBypclnt\fR(3NSL), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +This interface is unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. diff --git a/usr/src/man/man3nsl/ypclnt.3nsl b/usr/src/man/man3nsl/ypclnt.3nsl new file mode 100644 index 0000000000..e777e799e9 --- /dev/null +++ b/usr/src/man/man3nsl/ypclnt.3nsl @@ -0,0 +1,598 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ypclnt 3NSL "23 Jan 2004" "SunOS 5.11" "Networking Services Library Functions" +.SH NAME +ypclnt, yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first, yp_next, +yp_all, yp_order, yp_master, yperr_string, ypprot_err \- NIS Version 2 client +interface +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fB-flag\fR... ] \fIfile\fR\&.\|.\|. \fB-lnsl\fR [ \fIlibrary\fR...] +#include <rpcsvc/ypclnt.h> +#include <rpcsvc/yp_prot.h> + + + +\fBint\fR \fByp_bind\fR(\fBchar *\fR\fIindomain\fR); +.fi + +.LP +.nf +\fBvoid\fR \fByp_unbind\fR (\fBchar *\fR\fIindomain\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_get_default_domain\fR(\fBchar **\fR\fIoutdomain\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_match\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar *\fR\fIinkey\fR, \fBint\fR \fIinkeylen\fR, + \fBchar *\fR\fBchar **\fR\fIoutval\fR, \fBint *\fR\fIoutvallen\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_first\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar **\fR\fIoutkey\fR, \fBint *\fR\fIoutkeylen\fR, + \fBchar **\fR\fIoutval\fR, \fBint *\fR\fIoutvallen\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_next\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar *\fR\fIinkey\fR, \fBint *\fR\fIinkeylen\fR, + \fBchar **\fR\fIoutkey\fR, \fBint *\fR\fIoutkeylen\fR, \fBchar **\fR\fIoutval\fR, + \fBint *\fR\fIoutvallen\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_all\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBstruct ypall_callback *\fR\fIincallback\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_order\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBunsigned long *\fR\fIoutorder\fR); +.fi + +.LP +.nf +\fBint\fR \fByp_master\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar **\fR\fIoutname\fR); +.fi + +.LP +.nf +\fBchar *\fR\fByperr_string\fR(\fBint\fR \fIincode\fR); +.fi + +.LP +.nf +\fBint\fR \fBypprot_err\fR(\fBchar *\fR\fIdomain\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This package of functions provides an interface to \fBNIS\fR, Network +Information Service Version 2, formerly referred to as \fBYP\fR. In this +version of SunOS, \fBNIS\fR version 2 is supported only for compatibility with +previous versions. The recommended enterprise level information service is +\fBNIS+\fR or \fBNIS\fR version 3. See \fBNIS+\fR(1). The current SunOS +supports only the client interface to \fBNIS\fR version 2. This client +interface will in turn be served either by an existing \fBypserv\fR process +running on another machine on the network that has an earlier version of SunOS, +or by a \fBNIS+\fR server running in "YP-compatibility mode". See +\fBrpc.nisd\fR(1M). The \fBNOTES\fR section in \fBypfiles\fR(4) discusses the +implications of being an \fBNIS\fR client of an \fBNIS+\fR server in +\fBYP-compatibility mode\fR. For commands used to access \fBNIS\fR from a +client machine, see \fBypbind\fR(1M), \fBypwhich\fR(1), \fBypmatch\fR(1), and +\fBypcat\fR(1). The package can be loaded from the standard library, +\fB/usr/lib/libnsl.so.1\fR. +.sp +.LP +All input parameter names begin with \fIin\fR. Output parameters begin with +\fIout\fR. Output parameters of type \fBchar **\fR should be addresses of +uninitialized character pointers. Memory is allocated by the NIS client package +using \fBmalloc\fR(3C) and can be freed by the user code if it has no +continuing need for it. For each \fIoutkey\fR and \fIoutval\fR, two extra bytes +of memory are allocated at the end that contain NEWLINE and \fInull\fR, +respectively, but these two bytes are not reflected in \fIoutkeylen\fR or +\fIoutvallen\fR. The \fIindomain\fR and \fIinmap\fR strings must be non-null +and null-terminated. String parameters that are accompanied by a count +parameter may not be \fInull\fR, but they may point to null strings, with the +count parameter indicating this. Counted strings need not be null-terminated. +.sp +.LP +All functions in this package of type \fIint\fR return \fB0\fR if they succeed. +Otherwise, they return a failure code (\fBYPERR_\fR\fIxxxx\fR). Failure codes +are described in the \fBERRORS\fR section. +.SS "Routines" +.sp +.ne 2 +.mk +.na +\fB\fByp_bind()\fR\fR +.ad +.RS 27n +.rt +To use the NIS name services, the client process must be "bound" to an NIS +server that serves the appropriate domain using \fByp_bind()\fR. Binding need +not be done explicitly by user code. Binding is done automatically whenever an +NIS lookup function is called. The \fByp_bind()\fR function can be called +directly for processes that make use of a backup strategy , for example, a +local file in cases when NIS services are not available. A process should call +\fByp_unbind()\fR when it is finished using \fBNIS\fR in order to free up +resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_unbind()\fR\fR +.ad +.RS 27n +.rt +Each binding allocates or uses up one client process socket descriptor. Each +bound domain costs one socket descriptor. However, multiple requests to the +same domain use that same descriptor. The \fByp_unbind()\fR function is +available at the client interface for processes that explicitly manage their +socket descriptors while accessing multiple domains. The call to +\fByp_unbind()\fR makes the domain \fIunbound\fR, and frees all per-process and +per-node resources used to bind it. +.sp +If an RPC failure results upon use of a binding, that domain will be unbound +automatically. At that point, the \fBypclnt()\fR layer will retry a few more +times or until the operation succeeds, provided that \fBrpcbind\fR(1M) and +\fBypbind\fR(1M) are running, and either: +.RS +4 +.TP +.ie t \(bu +.el o +The client process cannot bind a server for the proper domain; or +.RE +.RS +4 +.TP +.ie t \(bu +.el o +RPC requests to the server fail. +.RE +.sp +.LP +Under the following circumstances, the \fBypclnt\fR layer will return control +to the user code, with either an error or success code and the results: +.RS +4 +.TP +.ie t \(bu +.el o +If an error is not RPC-related. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fBrpcbind\fR is not running. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fBypbind\fR is not running. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If a bound \fBypserv\fR process returns any answer (success or failure). +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_get_default_domain()\fR\fR +.ad +.RS 27n +.rt +\fBNIS\fR lookup calls require a map name and a domain name, at minimum. The +client process should know the name of the map of interest. Client processes +fetch the node's default domain by calling \fByp_get_default_domain()\fR and +use the returned \fIoutdomain\fR as the \fIindomain\fR parameter to successive +\fBNIS\fR name service calls. The domain returned is the same as that returned +using the \fBSI_SRPC_DOMAIN\fR command to the \fBsysinfo\fR(2) system call. The +value returned in \fIoutdomain\fR should not be freed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_match()\fR\fR +.ad +.RS 27n +.rt +The \fByp_match()\fR function returns the value associated with a passed key. +This key must be exact because no pattern matching is available. +\fByp_match()\fR requires a full YP map name, such as \fBhosts.byname\fR, +instead of the nickname \fBhosts\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_first()\fR\fR +.ad +.RS 27n +.rt +The \fByp_first()\fR function returns the first key-value pair from the named +map in the named domain. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_next()\fR\fR +.ad +.RS 27n +.rt +The \fByp_next()\fR function returns the next key-value pair in a named map. +The \fIinkey\fR parameter must be the \fIoutkey\fR returned from an initial +call to \fByp_first()\fR (to get the second key-value pair) or the one returned +from the \fIn\fRth call to \fByp_next()\fR (to get the \fIn\fRth + second +key-value pair). Similarly, the \fIinkeylen\fR parameter must be the +\fIoutkeylen\fR returned from the earlier \fByp_first()\fR or \fByp_next()\fR +call. +.sp +The concept of first and next is particular to the structure of the NIS map +being processed. Retrieval order is not related to either the lexical order +within any original (non-NIS name service) data base, or to any obvious +numerical sorting order on the keys, values, or key-value pairs. The only +ordering guarantee is that if the \fByp_first()\fR function is called on a +particular map, and then the \fByp_next()\fR function is repeatedly called on +the same map at the same server until the call fails with a reason of +\fBYPERR_NOMORE\fR, every entry in the data base is seen exactly once. Further, +if the same sequence of operations is performed on the same map at the same +server, the entries are seen in the same order. +.sp +Under conditions of heavy server load or server failure, the domain can become +unbound, then bound once again (perhaps to a different server) while a client +is running. This binding can cause a break in one of the enumeration rules. +Specific entries may be seen twice by the client, or not at all. This approach +protects the client from error messages that would otherwise be returned in the +midst of the enumeration. For a better solution to enumerating all entries in a +map, see \fByp_all()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_all()\fR\fR +.ad +.RS 27n +.rt +The \fByp_all()\fR function provides a way to transfer an entire map from +server to client in a single request using TCP (rather than UDP as with other +functions in this package). The entire transaction takes place as a single RPC +request and response. The \fByp_all()\fR function can be used just like any +other NIS name service procedure to identify the map in the normal manner and +to supply the name of a function that will be called to process each key-value +pair within the map. The call to \fByp_all()\fR returns only when the +transaction is completed (successfully or unsuccessfully), or the +\fBforeach()\fR function decides that it does not want to see any more +key-value pairs. +.sp +The third parameter to \fByp_all()\fR is: +.sp +.in +2 +.nf +struct ypall_callback *incallback { + int (*foreach)(\|); + char *data; +}; +.fi +.in -2 + +The function \fBforeach()\fR is called: +.sp +.in +2 +.nf +foreach(int \fIinstatus\fR, char *\fIinkey\fR, +int \fIinkeylen\fR, char *\fIinval\fR, +int \fIinvallen\fR, char *\fIindata\fR); +.fi +.in -2 + +The \fIinstatus\fR parameter holds one of the return status values defined in +<\fBrpcsvc/yp_prot.h\fR>, either \fBYP_TRUE\fR or an error code. See +\fBypprot_err()\fR, for a function that converts an NIS name service protocol +error code to a \fBypclnt\fR layer error code. +.sp +The key and value parameters are somewhat different than defined in the +synopsis section above. First, the memory pointed to by the \fIinkey\fR and +\fIinval\fR parameters is private to the \fByp_all()\fR function, and is +overwritten with the arrival of each new key-value pair. The \fBforeach()\fR +function must do something useful with the contents of that memory, but it does +not own the memory itself. Key and value objects presented to the +\fBforeach()\fR function look exactly as they do in the server's map. If they +were not NEWLINE-terminated or null-terminated in the map, they would not be +here either. +.sp +The \fIindata\fR parameter is the contents of the \fIincallback\fR->\fIdata\fR +element passed to \fByp_all()\fR. The \fBdata\fR element of the callback +structure can be used to share state information between the \fBforeach()\fR +function and the mainline code. Its use is optional, and no part of the NIS +client package inspects its contents; cast it to something useful, or ignore +it. The \fBforeach()\fR function is Boolean. It should return \fB0\fR to +indicate that it wants to be called again for further received key-value pairs, +or non-zero to stop the flow of key-value pairs. If \fBforeach()\fR returns a +non-zero value, it is not called again. The functional value of \fByp_all()\fR +is then \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_order()\fR\fR +.ad +.RS 27n +.rt +The \fByp_order()\fR function returns the order number for a map. The function +is not supported if the \fBypbind\fR process on the client's system is bound to +an \fBNIS+\fR server running in "YP-compatibility mode". +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByp_master()\fR\fR +.ad +.RS 27n +.rt +The \fByp_master()\fR function returns the machine name of the master NIS +server for a map. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fByperr_string()\fR\fR +.ad +.RS 27n +.rt +The \fByperr_string()\fR function returns a pointer to an error message string +that is null-terminated but contains no period or NEWLINE. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBypprot_err()\fR\fR +.ad +.RS 27n +.rt +The \fBypprot_err()\fR function takes an NIS name service protocol error code +as input, and returns a \fBypclnt()\fR layer error code, which can be used as +an input to \fByperr_string()\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +All integer functions return \fB0\fR if the requested operation is successful, +or one of the following errors if the operation fails: +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_ACCESS\fR\fR +.ad +.RS 17n +.rt +Access violation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_BADARGS\fR\fR +.ad +.RS 17n +.rt +The arguments to the function are bad. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_BADDB\fR\fR +.ad +.RS 17n +.rt +The \fBYP\fR database is bad. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_BUSY\fR\fR +.ad +.RS 17n +.rt +The database is busy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_DOMAIN\fR\fR +.ad +.RS 17n +.rt +Cannot bind to server on this domain. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_KEY\fR\fR +.ad +.RS 17n +.rt +No such key in map. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_MAP\fR\fR +.ad +.RS 17n +.rt +No such map in server's domain. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_NODOM\fR\fR +.ad +.RS 17n +.rt +Local domain name not set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_NOMORE\fR\fR +.ad +.RS 17n +.rt +No more records in map database. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_PMAP\fR\fR +.ad +.RS 17n +.rt +Cannot communicate with \fBrpcbind\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_RESRC\fR\fR +.ad +.RS 17n +.rt +Resource allocation failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_RPC\fR\fR +.ad +.RS 17n +.rt +\fBRPC\fR failure; domain has been unbound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_YPBIND\fR\fR +.ad +.RS 17n +.rt +Cannot communicate with \fBypbind\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_YPERR\fR\fR +.ad +.RS 17n +.rt +Internal \fBYP\fR server or client error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_YPSERV\fR\fR +.ad +.RS 17n +.rt +Cannot communicate with \fBypserv\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBYPERR_VERS\fR\fR +.ad +.RS 17n +.rt +\fBYP\fR version mismatch. +.RE + +.SH FILES +.sp +.LP +\fB/usr/lib/libnsl.so.1\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBNIS+\fR(1), \fBypcat\fR(1), \fBypmatch\fR(1), \fBypwhich\fR(1), +\fBrpc.nisd\fR(1M), \fBrpcbind\fR(1M), \fBypbind\fR(1M), \fBypserv\fR(1M), +\fBsysinfo\fR(2), \fBmalloc\fR(3C), \fBypfiles\fR(4), \fBattributes\fR(5) |