--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 AT&T Intellectual Property.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic rmr_init_man.xfm
+ Abstract The manual page for the rmr_init function.
+ Author E. Scott Daniels
+ Date 28 January 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_init
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+void* rmr_init( char* proto_port, int max_msg_size, int flags );
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_init) function prepares the environment for sending and receiving messages.
+It does so by establishing a worker thread (pthread) which subscribes to a route table
+generator which provides the necessary routing information for the RMR library to
+send messages.
+
+&space
+&ital(Port) is used to listen for connection requests from other RMR based applications.
+The value of &ital(max_msg_size) will be used when allocating zero copy send buffers
+which must be allocated, possibly, prior to the application knowing the actual size of
+a specific message.
+
+&space
+&h2(ENVIRONMENT)
+As a part of the initialisation process &cw(rmr_init) will look into the available
+environment variables to influence it's setup.
+The following variables will be used when found.
+&half_space
+
+&beg_dlist(1i : &bold_font )
+&ditem(RMR_SEED_RT)
+Assumes this is the filename of the seed route table file to use. In normal situations,
+the library will wait for an update from the route table generator (expected within a few seconds
+of initialisation) before being able to send messages.
+However, in some situations where a bootstrap table is necessary, this is the means to
+supply it to the library.
+&half_space
+
+&ditem(RMR_RTG_SVC)
+The route table generator assumes that RMr is listening on a well known port (4561) by
+default, but this environment variable can be used to change the listening port if
+needed.
+The value of the variable is expected to be just the port.
+&end_dlist
+
+&h2(RETURN VALUE)
+The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
+as the first parameter to nearly all other RMR functions.
+If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
+errno is set to an appropriate value.
+
+&h2(ERRORS)
+The following error values are specifically set by this RMR function. In some cases the
+error message of a system call is propagated up, and thus this list might be incomplete.
+
+&beg_dlist(.75i : ^&bold_font )
+&di(ENOMEM) Unable to allocate memory.
+&end_dlist
+
+&h2(EXAMPLE)
+&ex_start
+ void* uh;
+ rmr_mbuf* buf = NULL;
+
+ uh = rmr_init( "43086", 4096, 0 );
+ buf = rmr_rcv_msg( uh, buf );
+&ex_end
+
+&h2(SEE ALSO )
+rmr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_get_rcvfd(3),
+rmr_payload_size(3),
+rmr_send_msg(3),
+rmr_rcv_msg(3),
+rmr_rcv_specific(3),
+rmr_rts_msg(3),
+rmr_ready(3),
+rmr_fib(3),
+rmr_has_str(3),
+rmr_tokenise(3),
+rmr_mk_ring(3),
+rmr_ring_free(3)
+
+
+.qu
+
Code Review / ric-plt / lib / rmr.git / blobdiff