2 ==================================================================================
3 Copyright (c) 2019 Nokia
4 Copyright (c) 2018-2019 AT&T Intellectual Property.
6 Licensed under the Apache License, Version 2.0 (the "License");
7 you may not use this file except in compliance with the License.
8 You may obtain a copy of the License at
10 http://www.apache.org/licenses/LICENSE-2.0
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 ==================================================================================
21 Mnemonic rmr_init_man.xfm
22 Abstract The manual page for the rmr_init function.
23 Author E. Scott Daniels
27 .** if formatting with tfm, the roff.im will cause roff output to be generated
28 .** if formatting with pfm, then pretty postscript will be generated
31 .im &{lib}/generic_ps.im
33 .gv e OUTPUT_RST use_rst
43 &h1(RMR Library Functions)
52 void* rmr_init( char* proto_port, int max_msg_size, int flags );
58 The &cw(rmr_init) function prepares the environment for sending and receiving messages.
59 It does so by establishing a worker thread (pthread) which subscribes to a route table
60 generator which provides the necessary routing information for the RMR library to
64 &ital(Port) is used to listen for connection requests from other RMR based applications.
65 The value of &ital(max_msg_size) will be used when allocating zero copy send buffers
66 which must be allocated, possibly, prior to the application knowing the actual size of
71 As a part of the initialisation process &cw(rmr_init) will look into the available
72 environment variables to influence it's setup.
73 The following variables will be used when found.
76 &beg_dlist(1i : &bold_font )
78 Assumes this is the filename of the seed route table file to use. In normal situations,
79 the library will wait for an update from the route table generator (expected within a few seconds
80 of initialisation) before being able to send messages.
81 However, in some situations where a bootstrap table is necessary, this is the means to
82 supply it to the library.
86 The route table generator assumes that RMr is listening on a well known port (4561) by
87 default, but this environment variable can be used to change the listening port if
89 The value of the variable is expected to be just the port.
93 The &cw(rmr_init) function returns a void pointer (a contex if you will) that is passed
94 as the first parameter to nearly all other RMR functions.
95 If &cw(rmr_init) is unable to properly initialise the environment, NULL is returned and
96 errno is set to an appropriate value.
99 The following error values are specifically set by this RMR function. In some cases the
100 error message of a system call is propagated up, and thus this list might be incomplete.
102 &beg_dlist(.75i : ^&bold_font )
103 &di(ENOMEM) Unable to allocate memory.
109 rmr_mbuf* buf = NULL;
111 uh = rmr_init( "43086", 4096, 0 );
112 buf = rmr_rcv_msg( uh, buf );