X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr_init.3.xfm;fp=doc%2Fsrc%2Fman%2Frmr_init.3.xfm;h=408c95487a80af68acdbfff189ec619e9ab7214f;hb=fd9cc7a5b3355146388ebdf4d558cb284c66c5f1;hp=0000000000000000000000000000000000000000;hpb=008bc5b4414cebe48cecf63e8c817a02f7c3ce74;p=ric-plt%2Flib%2Frmr.git

diff --git a/doc/src/man/rmr_init.3.xfm b/doc/src/man/rmr_init.3.xfm
new file mode 100644
index 0000000..408c954
--- /dev/null
+++ b/doc/src/man/rmr_init.3.xfm
@@ -0,0 +1,134 @@
+.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
+