doc/src/man/rmr_init.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   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
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  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 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic        rmr_init_man.xfm
  22         Abstract        The manual page for the rmr_init function.
  23         Author          E. Scott Daniels
  24         Date            28 January 2019
  25 .fi
  26
  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
  29 .gv e LIB lib
  30 .if pfm
  31         .im &{lib}/generic_ps.im
  32 .ei
  33         .gv e OUTPUT_RST use_rst
  34         .if .ev &use_rst 1 =
  35                 .im &{lib}/rst.im
  36         .ei
  37                 .im &{lib}/roff.im
  38         .fi
  39 .fi
  40
  41 &line_len(6i)
  42
  43 &h1(RMR Library Functions)
  44 &h2(NAME)
  45         rmr_init
  46
  47 &h2(SYNOPSIS)
  48 &indent
  49 &ex_start
  50 #include <rmr/rmr.h>
  51
  52 void* rmr_init( char* proto_port, int max_msg_size, int flags );
  53 &ex_end
  54
  55 &uindent
  56
  57 &h2(DESCRIPTION)
  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
  61 send messages.
  62
  63 &space
  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
  67 a specific message.
  68
  69 &space
  70 &h2(ENVIRONMENT)
  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.
  74 &half_space
  75
  76 &beg_dlist(1i : &bold_font )
  77 &ditem(RMR_SEED_RT)
  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.
  83 &half_space
  84
  85 &ditem(RMR_RTG_SVC)
  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
  88 needed.
  89 The value of the variable is expected to be just the port.
  90 &end_dlist
  91
  92 &h2(RETURN VALUE)
  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.
  97
  98 &h2(ERRORS)
  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.
 101
 102 &beg_dlist(.75i : ^&bold_font )
 103 &di(ENOMEM) Unable to allocate memory.
 104 &end_dlist
 105
 106 &h2(EXAMPLE)
 107 &ex_start
 108    void*  uh;
 109    rmr_mbuf* buf = NULL;
 110
 111    uh = rmr_init( "43086", 4096, 0 );
 112    buf = rmr_rcv_msg( uh, buf );
 113 &ex_end
 114
 115 &h2(SEE ALSO )
 116 rmr_alloc_msg(3),
 117 rmr_call(3),
 118 rmr_free_msg(3),
 119 rmr_get_rcvfd(3),
 120 rmr_payload_size(3),
 121 rmr_send_msg(3),
 122 rmr_rcv_msg(3),
 123 rmr_rcv_specific(3),
 124 rmr_rts_msg(3),
 125 rmr_ready(3),
 126 rmr_fib(3),
 127 rmr_has_str(3),
 128 rmr_tokenise(3),
 129 rmr_mk_ring(3),
 130 rmr_ring_free(3)
 131
 132
 133 .qu
 134