~brightbox/bird/debian-packaging

(<I>struct fib *</I> <B>f</B>, <I>pool *</I> <B>p</B>, <I>unsigned</I> <B>node_size</B>, <I>unsigned</I> <B>hash_order</B>, <I>fib_init_func</I> <B>init</B>) -- initialize a new FIB

<P>

<H3>Arguments</H3>

<P>

<DL>

<DT><I>struct fib *</I> <B>f</B><DD><P>the FIB to be initialized (the structure itself being allocated by the caller)

<DT><I>pool *</I> <B>p</B><DD><P>pool to allocate the nodes in

<DT><I>unsigned</I> <B>node_size</B><DD><P>node size to be used (each node consists of a standard header <I>fib_node</I>

followed by user data)

<DT><I>unsigned</I> <B>hash_order</B><DD><P>initial hash order (a binary logarithm of hash table size), 0 to use default order

(recommended)

<DT><I>fib_init_func</I> <B>init</B><DD><P>pointer a function to be called to initialize a newly created node

</DL>

<H3>Description</H3>

<P>This function initializes a newly allocated FIB and prepares it for use.

<HR><H3>Function</H3>

(<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) -- search for FIB node by prefix

<P>

<H3>Arguments</H3>

<P>

<DL>

<DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in

<DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix

<DT><I>int</I> <B>len</B><DD><P>prefix length

</DL>

<H3>Description</H3>

<P>Search for a FIB node corresponding to the given prefix, return

a pointer to it or <I>NULL</I> if no such node exists.

<HR><H3>Function</H3>

(<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) -- find or create a FIB node

<P>

<H3>Arguments</H3>

<P>

<DL>

<DT><I>struct fib *</I> <B>f</B><DD><P>FIB to work with

<DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix

<DT><I>int</I> <B>len</B><DD><P>prefix length

</DL>

<H3>Description</H3>

<P>Search for a FIB node corresponding to the given prefix and

return a pointer to it. If no such node exists, create it.

<HR><H3>Function</H3>

<B>fib_route</B>

(<I>struct fib *</I> <B>f</B>, <I>ip_addr</I> <B>a</B>, <I>int</I> <B>len</B>) -- CIDR routing lookup

100

<P>

101

<H3>Arguments</H3>

102

<P>

103

<DL>

104

<DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in

105

<DT><I>ip_addr</I> <B>a</B><DD><P>pointer to IP address of the prefix

106

<DT><I>int</I> <B>len</B><DD><P>prefix length

107

</DL>

108

<H3>Description</H3>

109

<P>Search for a FIB node with longest prefix matching the given

110

network, that is a node which a CIDR router would use for routing

111

that network.

112

113

114

<HR><H3>Function</H3>

115

116

<B>fib_delete</B>

117

(<I>struct fib *</I> <B>f</B>, <I>void *</I> <B>E</B>) -- delete a FIB node

118

<P>

119

<H3>Arguments</H3>

120

<P>

121

<DL>

122

<DT><I>struct fib *</I> <B>f</B><DD><P>FIB to delete from

123

<DT><I>void *</I> <B>E</B><DD><P>entry to delete

124

</DL>

125

<H3>Description</H3>

126

<P>This function removes the given entry from the FIB,

127

taking care of all the asynchronous readers by shifting

128

them to the next node in the canonical reading order.

129

130

131

<HR><H3>Function</H3>

132

133

134

(<I>struct fib *</I> <B>f</B>) -- delete a FIB

135

<P>

136

<H3>Arguments</H3>

137

<P>

138

<DL>

139

<DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be deleted

140

</DL>

141

<H3>Description</H3>

142

<P>This function deletes a FIB -- it frees all memory associated

143

with it and all its entries.

144

145

146

<HR><H3>Function</H3>

147

148

<B>fib_check</B>

149

(<I>struct fib *</I> <B>f</B>) -- audit a FIB

150

<P>

151

<H3>Arguments</H3>

152

<P>

153

<DL>

154

<DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be checked

155

</DL>

156

<H3>Description</H3>

157

<P>This debugging function audits a FIB by checking its internal consistency.

158

Use when you suspect somebody of corrupting innocent data structures.

159

160

<H2><A NAME="ss2.2">2.2</A> <A HREF="prog.html#toc2.2">Routing tables</A>

161

</H2>

162

163

<P>

164

<P>Routing tables are probably the most important structures BIRD uses. They

165

hold all the information about known networks, the associated routes and

166

their attributes.

167

<P>There are multiple routing tables (a primary one together with any

168

number of secondary ones if requested by the configuration). Each table

169

is basically a FIB containing entries describing the individual

170

destination networks. For each network (represented by structure <I>net</I>),

171

there is a one-way linked list of route entries (<I>rte</I>), the first entry

172

on the list being the best one (i.e., the one we currently use

173

for routing), the order of the other ones is undetermined.

174

<P>The <I>rte</I> contains information specific to the route (preference, protocol

175

metrics, time of last modification etc.) and a pointer to a <I>rta</I> structure

176

(see the route attribute module for a precise explanation) holding the

177

remaining route attributes which are expected to be shared by multiple

178

routes in order to conserve memory.

179

<P>

180

<P><HR><H3>Function</H3>

181

182

183

(<I>net *</I> <B>net</B>, <I>struct proto *</I> <B>p</B>) -- find a route

184

<P>

185

<H3>Arguments</H3>

186

<P>

187

<DL>

188

<DT><I>net *</I> <B>net</B><DD><P>network node

189

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol

190

</DL>

191

<H3>Description</H3>

192

<P>The <B>rte_find()</B> function returns a route for destination <B>net</B>

193

which belongs has been defined by protocol <B>p</B>.

194

195

196

<HR><H3>Function</H3>

197

198

199

(<I>rta *</I> <B>a</B>) -- get a temporary <I>rte</I>

200

<P>

201

<H3>Arguments</H3>

202

<P>

203

<DL>

204

<DT><I>rta *</I> <B>a</B><DD><P>attributes to assign to the new route (a <I>rta</I>; in case it's

205

un-cached, <B>rte_update()</B> will create a cached copy automatically)

206

</DL>

207

<H3>Description</H3>

208

<P>Create a temporary <I>rte</I> and bind it with the attributes <B>a</B>.

209

Also set route preference to the default preference set for

210

the protocol.

211

212

213

<HR><H3>Function</H3>

214

215

<B>rte_announce</B>

216

(<I>rtable *</I> <B>tab</B>, <I>unsigned</I> <B>type</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>rte *</I> <B>before_old</B>, <I>ea_list *</I> <B>tmpa</B>) -- announce a routing table change

217

<P>

218

<H3>Arguments</H3>

219

<P>

220

<DL>

221

<DT><I>rtable *</I> <B>tab</B><DD><P>table the route has been added to

222

<DT><I>unsigned</I> <B>type</B><DD><P>type of route announcement (RA_OPTIMAL or RA_ANY)

223

<DT><I>net *</I> <B>net</B><DD><P>network in question

224

<DT><I>rte *</I> <B>new</B><DD><P>the new route to be announced

225

<DT><I>rte *</I> <B>old</B><DD><P>the previous route for the same network

226

<DT><I>rte *</I> <B>before_old</B><DD><P>-- undescribed --

227

<DT><I>ea_list *</I> <B>tmpa</B><DD><P>a list of temporary attributes belonging to the new route

228

</DL>

229

<H3>Description</H3>

230

<P>This function gets a routing table update and announces it

231

to all protocols that acccepts given type of route announcement

232

and are connected to the same table by their announcement hooks.

233

<P>Route announcement of type RA_OPTIMAL si generated when optimal

234

route (in routing table <B>tab</B>) changes. In that case <B>old</B> stores the

235

old optimal route.

236

<P>Route announcement of type RA_ANY si generated when any route (in

237

routing table <B>tab</B>) changes In that case <B>old</B> stores the old route

238

from the same protocol.

239

<P>For each appropriate protocol, we first call its <B>import_control()</B>

240

hook which performs basic checks on the route (each protocol has a

241

right to veto or force accept of the route before any filter is

242

asked) and adds default values of attributes specific to the new

243

protocol (metrics, tags etc.). Then it consults the protocol's

244

export filter and if it accepts the route, the <B>rt_notify()</B> hook of

245

the protocol gets called.

246

247

248

<HR><H3>Function</H3>

249

250

251

(<I>rte *</I> <B>e</B>) -- delete a <I>rte</I>

252

<P>

253

<H3>Arguments</H3>

254

<P>

255

<DL>

256

<DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be deleted

257

</DL>

258

<H3>Description</H3>

259

<P><B>rte_free()</B> deletes the given <I>rte</I> from the routing table it's linked to.

260

261

262

<HR><H3>Function</H3>

263

264

<B>rte_update2</B>

265

(<I>struct announce_hook *</I> <B>ah</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>struct proto *</I> <B>src</B>) -- enter a new update to a routing table

266

<P>

267

<H3>Arguments</H3>

268

<P>

269

<DL>

270

<DT><I>struct announce_hook *</I> <B>ah</B><DD><P>pointer to table announce hook

271

<DT><I>net *</I> <B>net</B><DD><P>network node

272

<DT><I>rte *</I> <B>new</B><DD><P>a <I>rte</I> representing the new route or <I>NULL</I> for route removal.

273

<DT><I>struct proto *</I> <B>src</B><DD><P>protocol originating the update

274

</DL>

275

<H3>Description</H3>

276

<P>This function is called by the routing protocols whenever they discover

277

a new route or wish to update/remove an existing route. The right announcement

278

sequence is to build route attributes first (either un-cached with <B>aflags</B> set

279

to zero or a cached one using <B>rta_lookup()</B>; in this case please note that

280

you need to increase the use count of the attributes yourself by calling

281

<B>rta_clone()</B>), call <B>rte_get_temp()</B> to obtain a temporary <I>rte</I>, fill in all

282

the appropriate data and finally submit the new <I>rte</I> by calling <B>rte_update()</B>.

283

<P><B>src</B> specifies the protocol that originally created the route and the meaning

284

of protocol-dependent data of <B>new</B>. If <B>new</B> is not <I>NULL</I>, <B>src</B> have to be the

285

same value as <B>new</B>->attrs->proto. <B>p</B> specifies the protocol that called

286

<B>rte_update()</B>. In most cases it is the same protocol as <B>src</B>. <B>rte_update()</B>

287

stores <B>p</B> in <B>new</B>->sender;

288

<P>When <B>rte_update()</B> gets any route, it automatically validates it (checks,

289

whether the network and next hop address are valid IP addresses and also

290

whether a normal routing protocol doesn't try to smuggle a host or link

291

scope route to the table), converts all protocol dependent attributes stored

292

in the <I>rte</I> to temporary extended attributes, consults import filters of the

293

protocol to see if the route should be accepted and/or its attributes modified,

294

stores the temporary attributes back to the <I>rte</I>.

295

<P>Now, having a "public" version of the route, we

296

automatically find any old route defined by the protocol <B>src</B>

297

for network <B>n</B>, replace it by the new one (or removing it if <B>new</B> is <I>NULL</I>),

298

recalculate the optimal route for this destination and finally broadcast

299

the change (if any) to all routing protocols by calling <B>rte_announce()</B>.

300

<P>All memory used for attribute lists and other temporary allocations is taken

301

from a special linear pool <B>rte_update_pool</B> and freed when <B>rte_update()</B>

302

finishes.

303

304

305

<HR><H3>Function</H3>

306

307

308

(<I>rte *</I> <B>e</B>) -- dump a route

309

<P>

310

<H3>Arguments</H3>

311

<P>

312

<DL>

313

<DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be dumped

314

</DL>

315

<H3>Description</H3>

316

<P>This functions dumps contents of a <I>rte</I> to debug output.

317

318

319

<HR><H3>Function</H3>

320

321

322

(<I>rtable *</I> <B>t</B>) -- dump a routing table

323

<P>

324

<H3>Arguments</H3>

325

<P>

326

<DL>

327

<DT><I>rtable *</I> <B>t</B><DD><P>routing table to be dumped

328

</DL>

329

<H3>Description</H3>

330

<P>This function dumps contents of a given routing table to debug output.

331

332

333

<HR><H3>Function</H3>

334

335

336

(<B>void</B>) -- dump all routing tables

337

<P>

338

<H3>Description</H3>

339

<P>

340

<P>This function dumps contents of all routing tables to debug output.

341

342

343

<HR><H3>Function</H3>

344

345

346

(<B>void</B>) -- initialize routing tables

347

<P>

348

<H3>Description</H3>

349

<P>

350

<P>This function is called during BIRD startup. It initializes the

351

routing table module.

352

353

354

<HR><H3>Function</H3>

355

356

<B>rt_prune_loop</B>

357

(<B>void</B>) -- prune routing tables

358

<P>

359

<H3>Description</H3>

360

<P>

361

<P>The prune loop scans routing tables and removes routes belonging to

362

flushing protocols and also stale network entries. Returns 1 when

363

all such routes are pruned. It is a part of the protocol flushing

364

loop.

365

<P>The prune loop runs in two steps. In the first step it prunes just

366

the routes with flushing senders (in explicitly marked tables) so

367

the route removal is propagated as usual. In the second step, all

368

remaining relevant routes are removed. Ideally, there shouldn't be

369

any, but it happens when pipe filters are changed.

370

371

372

<HR><H3>Function</H3>

373

374

<B>rt_lock_table</B>

375

(<I>rtable *</I> <B>r</B>) -- lock a routing table

376

<P>

377

<H3>Arguments</H3>

378

<P>

379

<DL>

380

<DT><I>rtable *</I> <B>r</B><DD><P>routing table to be locked

381

</DL>

382

<H3>Description</H3>

383

<P>Lock a routing table, because it's in use by a protocol,

384

preventing it from being freed when it gets undefined in a new

385

configuration.

386

387

388

<HR><H3>Function</H3>

389

390

<B>rt_unlock_table</B>

391

(<I>rtable *</I> <B>r</B>) -- unlock a routing table

392

<P>

393

<H3>Arguments</H3>

394

<P>

395

<DL>

396

<DT><I>rtable *</I> <B>r</B><DD><P>routing table to be unlocked

397

</DL>

398

<H3>Description</H3>

399

<P>Unlock a routing table formerly locked by <B>rt_lock_table()</B>,

400

that is decrease its use count and delete it if it's scheduled

401

for deletion by configuration changes.

402

403

404

<HR><H3>Function</H3>

405

406

<B>rt_commit</B>

407

(<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>) -- commit new routing table configuration

408

<P>

409

<H3>Arguments</H3>

410

<P>

411

<DL>

412

<DT><I>struct config *</I> <B>new</B><DD><P>new configuration

413

<DT><I>struct config *</I> <B>old</B><DD><P>original configuration or <I>NULL</I> if it's boot time config

414

</DL>

415

<H3>Description</H3>

416

<P>Scan differences between <B>old</B> and <B>new</B> configuration and modify

417

the routing tables according to these changes. If <B>new</B> defines a

418

previously unknown table, create it, if it omits a table existing

419

in <B>old</B>, schedule it for deletion (it gets deleted when all protocols

420

disconnect from it by calling <B>rt_unlock_table()</B>), if it exists

421

in both configurations, leave it unchanged.

422

423

424

<HR><H3>Function</H3>

425

426

427

(<I>struct proto *</I> <B>p</B>) -- advertise routes to a new protocol

428

<P>

429

<H3>Arguments</H3>

430

<P>

431

<DL>

432

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol to be fed

433

</DL>

434

<H3>Description</H3>

435

<P>This function performs one pass of advertisement of routes to a newly

436

initialized protocol. It's called by the protocol code as long as it

437

has something to do. (We avoid transferring all the routes in single

438

pass in order not to monopolize CPU time.)

439

440

441

<HR><H3>Function</H3>

442

443

<B>rt_feed_baby_abort</B>

444

(<I>struct proto *</I> <B>p</B>) -- abort protocol feeding

445

<P>

446

<H3>Arguments</H3>

447

<P>

448

<DL>

449

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol

450

</DL>

451

<H3>Description</H3>

452

<P>This function is called by the protocol code when the protocol

453

stops or ceases to exist before the last iteration of <B>rt_feed_baby()</B>

454

has finished.

455

456

457

<HR><H3>Function</H3>

458

459

460

(<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) -- find a network entry

461

<P>

462

<H3>Arguments</H3>

463

<P>

464

<DL>

465

<DT><I>rtable *</I> <B>tab</B><DD><P>a routing table

466

<DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network

467

<DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix

468

</DL>

469

<H3>Description</H3>

470

<P><B>net_find()</B> looks up the given network in routing table <B>tab</B> and

471

returns a pointer to its <I>net</I> entry or <I>NULL</I> if no such network

472

exists.

473

474

475

<HR><H3>Function</H3>

476

477

478

(<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) -- obtain a network entry

479

<P>

480

<H3>Arguments</H3>

481

<P>

482

<DL>

483

<DT><I>rtable *</I> <B>tab</B><DD><P>a routing table

484

<DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network

485

<DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix

486

</DL>

487

<H3>Description</H3>

488

<P><B>net_get()</B> looks up the given network in routing table <B>tab</B> and

489

returns a pointer to its <I>net</I> entry. If no such entry exists, it's

490

created.

491

492

493

<HR><H3>Function</H3>

494

495

496

(<I>rte *</I> <B>r</B>) -- copy a route for writing

497

<P>

498

<H3>Arguments</H3>

499

<P>

500

<DL>

501

<DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied

502

</DL>

503

<H3>Description</H3>

504

<P><B>rte_cow()</B> takes a <I>rte</I> and prepares it for modification. The exact action

505

taken depends on the flags of the <I>rte</I> -- if it's a temporary entry, it's

506

just returned unchanged, else a new temporary entry with the same contents

507

is created.

508

<P>The primary use of this function is inside the filter machinery -- when

509

a filter wants to modify <I>rte</I> contents (to change the preference or to

510

attach another set of attributes), it must ensure that the <I>rte</I> is not

511

shared with anyone else (and especially that it isn't stored in any routing

512

table).

513

<H3>Result</H3>

514

<P>a pointer to the new writable <I>rte</I>.

515

516

<H2><A NAME="ss2.3">2.3</A> <A HREF="prog.html#toc2.3">Route attribute cache</A>

517

</H2>

518

519

<P>

520

<P>Each route entry carries a set of route attributes. Several of them

521

vary from route to route, but most attributes are usually common

522

for a large number of routes. To conserve memory, we've decided to

523

store only the varying ones directly in the <I>rte</I> and hold the rest

524

in a special structure called <I>rta</I> which is shared among all the

525

<I>rte</I>'s with these attributes.

526

<P>Each <I>rta</I> contains all the static attributes of the route (i.e.,

527

those which are always present) as structure members and a list of

528

dynamic attributes represented by a linked list of <I>ea_list</I>

529

structures, each of them consisting of an array of <I>eattr</I>'s containing

530

the individual attributes. An attribute can be specified more than once

531

in the <I>ea_list</I> chain and in such case the first occurrence overrides

532

the others. This semantics is used especially when someone (for example

533

a filter) wishes to alter values of several dynamic attributes, but

534

it wants to preserve the original attribute lists maintained by

535

another module.

536

<P>Each <I>eattr</I> contains an attribute identifier (split to protocol ID and

537

per-protocol attribute ID), protocol dependent flags, a type code (consisting

538

of several bit fields describing attribute characteristics) and either an

539

embedded 32-bit value or a pointer to a <I>adata</I> structure holding attribute

540

contents.

541

<P>There exist two variants of <I>rta</I>'s -- cached and un-cached ones. Un-cached

542

<I>rta</I>'s can have arbitrarily complex structure of <I>ea_list</I>'s and they

543

can be modified by any module in the route processing chain. Cached

544

<I>rta</I>'s have their attribute lists normalized (that means at most one

545

<I>ea_list</I> is present and its values are sorted in order to speed up

546

searching), they are stored in a hash table to make fast lookup possible

547

and they are provided with a use count to allow sharing.

548

<P>Routing tables always contain only cached <I>rta</I>'s.

549

<P>

550

<P><HR><H3>Function</H3>

551

<P><I>eattr *</I>

552

553

(<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>) -- find an extended attribute

554

<P>

555

<H3>Arguments</H3>

556

<P>

557

<DL>

558

<DT><I>ea_list *</I> <B>e</B><DD><P>attribute list to search in

559

<DT><I>unsigned</I> <B>id</B><DD><P>attribute ID to search for

560

</DL>

561

<H3>Description</H3>

562

<P>Given an extended attribute list, <B>ea_find()</B> searches for a first

563

occurrence of an attribute with specified ID, returning either a pointer

564

to its <I>eattr</I> structure or <I>NULL</I> if no such attribute exists.

565

566

567

<HR><H3>Function</H3>

568

569

570

(<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>, <I>int</I> <B>def</B>) -- fetch an integer attribute

571

<P>

572

<H3>Arguments</H3>

573

<P>

574

<DL>

575

<DT><I>ea_list *</I> <B>e</B><DD><P>attribute list

576

<DT><I>unsigned</I> <B>id</B><DD><P>attribute ID

577

<DT><I>int</I> <B>def</B><DD><P>default value

578

</DL>

579

<H3>Description</H3>

580

<P>This function is a shortcut for retrieving a value of an integer attribute

581

by calling <B>ea_find()</B> to find the attribute, extracting its value or returning

582

a provided default if no such attribute is present.

583

584

585

<HR><H3>Function</H3>

586

587

588

(<I>ea_list *</I> <B>e</B>) -- sort an attribute list

589

<P>

590

<H3>Arguments</H3>

591

<P>

592

<DL>

593

<DT><I>ea_list *</I> <B>e</B><DD><P>list to be sorted

594

</DL>

595

<H3>Description</H3>

596

<P>This function takes a <I>ea_list</I> chain and sorts the attributes

597

within each of its entries.

598

<P>If an attribute occurs multiple times in a single <I>ea_list</I>,

599

<B>ea_sort()</B> leaves only the first (the only significant) occurrence.

600

601

602

<HR><H3>Function</H3>

603

<P><I>unsigned</I>

604

605

(<I>ea_list *</I> <B>e</B>) -- estimate attribute list size

606

<P>

607

<H3>Arguments</H3>

608

<P>

609

<DL>

610

<DT><I>ea_list *</I> <B>e</B><DD><P>attribute list

611

</DL>

612

<H3>Description</H3>

613

<P>This function calculates an upper bound of the size of

614

a given <I>ea_list</I> after merging with <B>ea_merge()</B>.

615

616

617

<HR><H3>Function</H3>

618

619

<B>ea_merge</B>

620

(<I>ea_list *</I> <B>e</B>, <I>ea_list *</I> <B>t</B>) -- merge segments of an attribute list

621

<P>

622

<H3>Arguments</H3>

623

<P>

624

<DL>

625

<DT><I>ea_list *</I> <B>e</B><DD><P>attribute list

626

<DT><I>ea_list *</I> <B>t</B><DD><P>buffer to store the result to

627

</DL>

628

<H3>Description</H3>

629

<P>This function takes a possibly multi-segment attribute list

630

and merges all of its segments to one.

631

<P>The primary use of this function is for <I>ea_list</I> normalization:

632

first call <B>ea_scan()</B> to determine how much memory will the result

633

take, then allocate a buffer (usually using <B>alloca()</B>), merge the

634

segments with <B>ea_merge()</B> and finally sort and prune the result

635

by calling <B>ea_sort()</B>.

636

637

638

<HR><H3>Function</H3>

639

640

641

(<I>ea_list *</I> <B>x</B>, <I>ea_list *</I> <B>y</B>) -- compare two <I>ea_list</I>'s

642

<P>

643

<H3>Arguments</H3>

644

<P>

645

<DL>

646

<DT><I>ea_list *</I> <B>x</B><DD><P>attribute list

647

<DT><I>ea_list *</I> <B>y</B><DD><P>attribute list

648

</DL>

649

<H3>Description</H3>

650

<P><B>ea_same()</B> compares two normalized attribute lists <B>x</B> and <B>y</B> and returns

651

1 if they contain the same attributes, 0 otherwise.

652

653

654

<HR><H3>Function</H3>

655

656

657

(<I>struct cli *</I> <B>c</B>, <I>eattr *</I> <B>e</B>) -- print an <I>eattr</I> to CLI

658

<P>

659

<H3>Arguments</H3>

660

<P>

661

<DL>

662

<DT><I>struct cli *</I> <B>c</B><DD><P>destination CLI

663

<DT><I>eattr *</I> <B>e</B><DD><P>attribute to be printed

664

</DL>

665

<H3>Description</H3>

666

<P>This function takes an extended attribute represented by its <I>eattr</I>

667

structure and prints it to the CLI according to the type information.

668

<P>If the protocol defining the attribute provides its own

669

<B>get_attr()</B> hook, it's consulted first.

670

671

672

<HR><H3>Function</H3>

673

674

675

(<I>ea_list *</I> <B>e</B>) -- dump an extended attribute

676

<P>

677

<H3>Arguments</H3>

678

<P>

679

<DL>

680

<DT><I>ea_list *</I> <B>e</B><DD><P>attribute to be dumped

681

</DL>

682

<H3>Description</H3>

683

<P><B>ea_dump()</B> dumps contents of the extended attribute given to

684

the debug output.

685

686

687

<HR><H3>Function</H3>

688

<P><I>unsigned int</I>

689

690

(<I>ea_list *</I> <B>e</B>) -- calculate an <I>ea_list</I> hash key

691

<P>

692

<H3>Arguments</H3>

693

<P>

694

<DL>

695

<DT><I>ea_list *</I> <B>e</B><DD><P>attribute list

696

</DL>

697

<H3>Description</H3>

698

<P><B>ea_hash()</B> takes an extended attribute list and calculated a hopefully

699

uniformly distributed hash value from its contents.

700

701

702

<HR><H3>Function</H3>

703

704

<B>ea_append</B>

705

(<I>ea_list *</I> <B>to</B>, <I>ea_list *</I> <B>what</B>) -- concatenate <I>ea_list</I>'s

706

<P>

707

<H3>Arguments</H3>

708

<P>

709

<DL>

710

<DT><I>ea_list *</I> <B>to</B><DD><P>destination list (can be <I>NULL</I>)

711

<DT><I>ea_list *</I> <B>what</B><DD><P>list to be appended (can be <I>NULL</I>)

712

</DL>

713

<H3>Description</H3>

714

<P>This function appends the <I>ea_list</I> <B>what</B> at the end of

715

<I>ea_list</I> <B>to</B> and returns a pointer to the resulting list.

716

717

718

<HR><H3>Function</H3>

719

720

<B>rta_lookup</B>

721

(<I>rta *</I> <B>o</B>) -- look up a <I>rta</I> in attribute cache

722

<P>

723

<H3>Arguments</H3>

724

<P>

725

<DL>

726

<DT><I>rta *</I> <B>o</B><DD><P>a un-cached <I>rta</I>

727

</DL>

728

<H3>Description</H3>

729

<P><B>rta_lookup()</B> gets an un-cached <I>rta</I> structure and returns its cached

730

counterpart. It starts with examining the attribute cache to see whether

731

there exists a matching entry. If such an entry exists, it's returned and

732

its use count is incremented, else a new entry is created with use count

733

set to 1.

734

<P>The extended attribute lists attached to the <I>rta</I> are automatically

735

converted to the normalized form.

736

737

738

<HR><H3>Function</H3>

739

740

741

(<I>rta *</I> <B>a</B>) -- dump route attributes

742

<P>

743

<H3>Arguments</H3>

744

<P>

745

<DL>

746

<DT><I>rta *</I> <B>a</B><DD><P>attribute structure to dump

747

</DL>

748

<H3>Description</H3>

749

<P>This function takes a <I>rta</I> and dumps its contents to the debug output.

750

751

752

<HR><H3>Function</H3>

753

754

755

(<B>void</B>) -- dump attribute cache

756

<P>

757

<H3>Description</H3>

758

<P>

759

<P>This function dumps the whole contents of route attribute cache

760

to the debug output.

761

762

763

<HR><H3>Function</H3>

764

765

766

(<B>void</B>) -- initialize route attribute cache

767

<P>

768

<H3>Description</H3>

769

<P>

770

<P>This function is called during initialization of the routing

771

table module to set up the internals of the attribute cache.

772

773

774

<HR><H3>Function</H3>

775

776

<B>rta_clone</B>

777

(<I>rta *</I> <B>r</B>) -- clone route attributes

778

<P>

779

<H3>Arguments</H3>

780

<P>

781

<DL>

782

<DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be cloned

783

</DL>

784

<H3>Description</H3>

785

<P><B>rta_clone()</B> takes a cached <I>rta</I> and returns its identical cached

786

copy. Currently it works by just returning the original <I>rta</I> with

787

its use count incremented.

788

789

790

<HR><H3>Function</H3>

791

792

793

(<I>rta *</I> <B>r</B>) -- free route attributes

794

<P>

795

<H3>Arguments</H3>

796

<P>

797

<DL>

798

<DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be freed

799

</DL>

800

<H3>Description</H3>

801

<P>If you stop using a <I>rta</I> (for example when deleting a route which uses

802

it), you need to call <B>rta_free()</B> to notify the attribute cache the

803

attribute is no longer in use and can be freed if you were the last

804

user (which <B>rta_free()</B> tests by inspecting the use count).

805

806

<P>

807

<H2><A NAME="ss2.4">2.4</A> <A HREF="prog.html#toc2.4">Routing protocols</A>

808

</H2>

809

810

<H3>Introduction</H3>

811

812

<P>The routing protocols are the bird's heart and a fine amount of code

813

is dedicated to their management and for providing support functions to them.

814

(-: Actually, this is the reason why the directory with sources of the core

815

code is called <CODE>nest</CODE> :-).

816

<P>

817

<P>When talking about protocols, one need to distinguish between <EM>protocols</EM>

818

and protocol <EM>instances</EM>. A protocol exists exactly once, not depending on whether

819

it's configured or not and it can have an arbitrary number of instances corresponding

820

to its "incarnations" requested by the configuration file. Each instance is completely

821

autonomous, has its own configuration, its own status, its own set of routes and its

822

own set of interfaces it works on.

823

<P>

824

<P>A protocol is represented by a <I>protocol</I> structure containing all the basic

825

information (protocol name, default settings and pointers to most of the protocol

826

hooks). All these structures are linked in the <B>protocol_list</B> list.

827

<P>

828

<P>Each instance has its own <I>proto</I> structure describing all its properties: protocol

829

type, configuration, a resource pool where all resources belonging to the instance

830

live, various protocol attributes (take a look at the declaration of <I>proto</I> in

831

<CODE>protocol.h</CODE>), protocol states (see below for what do they mean), connections

832

to routing tables, filters attached to the protocol

833

and finally a set of pointers to the rest of protocol hooks (they

834

are the same for all instances of the protocol, but in order to avoid extra

835

indirections when calling the hooks from the fast path, they are stored directly

836

in <I>proto</I>). The instance is always linked in both the global instance list

837

(<B>proto_list</B>) and a per-status list (either <B>active_proto_list</B> for

838

running protocols, <B>initial_proto_list</B> for protocols being initialized or

839

<B>flush_proto_list</B> when the protocol is being shut down).

840

<P>

841

<P>The protocol hooks are described in the next chapter, for more information about

842

configuration of protocols, please refer to the configuration chapter and also

843

to the description of the <B>proto_commit</B> function.

844

<P>

845

<H3>Protocol states</H3>

846

847

<P>As startup and shutdown of each protocol are complex processes which can be affected

848

by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),

849

we have decided to supervise them by a pair of simple state machines -- the protocol

850

state machine and a core state machine.

851

<P>

852

<P>The <EM>protocol state machine</EM> corresponds to internal state of the protocol

853

and the protocol can alter its state whenever it wants to. There are

854

the following states:

855

<P>

856

<DL>

857

<DT><CODE>PS_DOWN</CODE><DD><P>The protocol is down and waits for being woken up by calling its

858

start() hook.

859

<DT><CODE>PS_START</CODE><DD><P>The protocol is waiting for connection with the rest of the

860

network. It's active, it has resources allocated, but it still doesn't want

861

any routes since it doesn't know what to do with them.

862

<DT><CODE>PS_UP</CODE><DD><P>The protocol is up and running. It communicates with the core,

863

delivers routes to tables and wants to hear announcement about route changes.

864

<DT><CODE>PS_STOP</CODE><DD><P>The protocol has been shut down (either by being asked by the

865

core code to do so or due to having encountered a protocol error).

866

</DL>

867

<P>

868

<P>Unless the protocol is in the <CODE>PS_DOWN</CODE> state, it can decide to change

869

its state by calling the <B>proto_notify_state</B> function.

870

<P>

871

<P>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.

872

<P>

873

<P>The <EM>core state machine</EM> takes care of the core view of protocol state.

874

The states are traversed according to changes of the protocol state machine, but

875

sometimes the transitions are delayed if the core needs to finish some actions

876

(for example sending of new routes to the protocol) before proceeding to the

877

new state. There are the following core states:

878

<P>

879

<DL>

880

<DT><CODE>FS_HUNGRY</CODE><DD><P>The protocol is down, it doesn't have any routes and

881

doesn't want them.

882

<DT><CODE>FS_FEEDING</CODE><DD><P>The protocol has reached the <CODE>PS_UP</CODE> state, but

883

we are still busy sending the initial set of routes to it.

884

<DT><CODE>FS_HAPPY</CODE><DD><P>The protocol is up and has complete routing information.

885

<DT><CODE>FS_FLUSHING</CODE><DD><P>The protocol is shutting down (it's in either <CODE>PS_STOP</CODE>

886

or <CODE>PS_DOWN</CODE> state) and we're flushing all of its routes from the

887

routing tables.

888

</DL>

889

<P>

890

<H3>Functions of the protocol module</H3>

891

892

<P>The protocol module provides the following functions:

893

<HR><H3>Function</H3>

894

895

<B>proto_new</B>

896

(<I>struct proto_config *</I> <B>c</B>, <I>unsigned</I> <B>size</B>) -- create a new protocol instance

897

<P>

898

<H3>Arguments</H3>

899

<P>

900

<DL>

901

<DT><I>struct proto_config *</I> <B>c</B><DD><P>protocol configuration

902

<DT><I>unsigned</I> <B>size</B><DD><P>size of protocol data structure (each protocol instance is represented by

903

a structure starting with generic part [struct <I>proto</I>] and continued

904

with data specific to the protocol)

905

</DL>

906

<H3>Description</H3>

907

<P>When a new configuration has been read in, the core code starts

908

initializing all the protocol instances configured by calling their

909

<B>init()</B> hooks with the corresponding instance configuration. The initialization

910

code of the protocol is expected to create a new instance according to the

911

configuration by calling this function and then modifying the default settings

912

to values wanted by the protocol.

913

914

915

<HR><H3>Function</H3>

916

<P><I>struct announce_hook *</I>

917

<B>proto_add_announce_hook</B>

918

(<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>, <I>struct proto_stats *</I> <B>stats</B>) -- connect protocol to a routing table

919

<P>

920

<H3>Arguments</H3>

921

<P>

922

<DL>

923

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

924

<DT><I>struct rtable *</I> <B>t</B><DD><P>routing table to connect to

925

<DT><I>struct proto_stats *</I> <B>stats</B><DD><P>per-table protocol statistics

926

</DL>

927

<H3>Description</H3>

928

<P>This function creates a connection between the protocol instance <B>p</B>

929

and the routing table <B>t</B>, making the protocol hear all changes in

930

the table.

931

<P>The announce hook is linked in the protocol ahook list and, if the

932

protocol accepts routes, also in the table ahook list. Announce

933

hooks are allocated from the routing table resource pool, they are

934

unlinked from the table ahook list after the protocol went down,

935

(in <B>proto_schedule_flush()</B>) and they are automatically freed after the

936

protocol is flushed (in <B>proto_fell_down()</B>).

937

<P>Unless you want to listen to multiple routing tables (as the Pipe

938

protocol does), you needn't to worry about this function since the

939

connection to the protocol's primary routing table is initialized

940

automatically by the core code.

941

942

943

<HR><H3>Function</H3>

944

<P><I>struct announce_hook *</I>

945

<B>proto_find_announce_hook</B>

946

(<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>) -- find announce hooks

947

<P>

948

<H3>Arguments</H3>

949

<P>

950

<DL>

951

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

952

<DT><I>struct rtable *</I> <B>t</B><DD><P>routing table

953

</DL>

954

<H3>Description</H3>

955

<P>Returns pointer to announce hook or NULL

956

957

958

<HR><H3>Function</H3>

959

960

<B>proto_config_new</B>

961

(<I>struct protocol *</I> <B>pr</B>, <I>unsigned</I> <B>size</B>, <I>int</I> <B>class</B>) -- create a new protocol configuration

962

<P>

963

<H3>Arguments</H3>

964

<P>

965

<DL>

966

<DT><I>struct protocol *</I> <B>pr</B><DD><P>protocol the configuration will belong to

967

<DT><I>unsigned</I> <B>size</B><DD><P>size of the structure including generic data

968

<DT><I>int</I> <B>class</B><DD><P>SYM_PROTO or SYM_TEMPLATE

969

</DL>

970

<H3>Description</H3>

971

<P>Whenever the configuration file says that a new instance

972

of a routing protocol should be created, the parser calls

973

<B>proto_config_new()</B> to create a configuration entry for this

974

instance (a structure staring with the <I>proto_config</I> header

975

containing all the generic items followed by protocol-specific

976

ones). Also, the configuration entry gets added to the list

977

of protocol instances kept in the configuration.

978

<P>The function is also used to create protocol templates (when class

979

SYM_TEMPLATE is specified), the only difference is that templates

980

are not added to the list of protocol instances and therefore not

981

initialized during <B>protos_commit()</B>).

982

983

984

<HR><H3>Function</H3>

985

986

<B>proto_copy_config</B>

987

(<I>struct proto_config *</I> <B>dest</B>, <I>struct proto_config *</I> <B>src</B>) -- copy a protocol configuration

988

<P>

989

<H3>Arguments</H3>

990

<P>

991

<DL>

992

<DT><I>struct proto_config *</I> <B>dest</B><DD><P>destination protocol configuration

993

<DT><I>struct proto_config *</I> <B>src</B><DD><P>source protocol configuration

994

</DL>

995

<H3>Description</H3>

996

<P>Whenever a new instance of a routing protocol is created from the

997

template, <B>proto_copy_config()</B> is called to copy a content of

998

the source protocol configuration to the new protocol configuration.

999

Name, class and a node in protos list of <B>dest</B> are kept intact.

1000

<B>copy_config()</B> protocol hook is used to copy protocol-specific data.

1001

1002

1003

<HR><H3>Function</H3>

1004

1005

<B>protos_preconfig</B>

1006

(<I>struct config *</I> <B>c</B>) -- pre-configuration processing

1007

<P>

1008

<H3>Arguments</H3>

1009

<P>

1010

<DL>

1011

<DT><I>struct config *</I> <B>c</B><DD><P>new configuration

1012

</DL>

1013

<H3>Description</H3>

1014

<P>This function calls the <B>preconfig()</B> hooks of all routing

1015

protocols available to prepare them for reading of the new

1016

configuration.

1017

1018

1019

<HR><H3>Function</H3>

1020

1021

<B>protos_postconfig</B>

1022

(<I>struct config *</I> <B>c</B>) -- post-configuration processing

1023

<P>

1024

<H3>Arguments</H3>

1025

<P>

1026

<DL>

1027

<DT><I>struct config *</I> <B>c</B><DD><P>new configuration

1028

</DL>

1029

<H3>Description</H3>

1030

<P>This function calls the <B>postconfig()</B> hooks of all protocol

1031

instances specified in configuration <B>c</B>. The hooks are not

1032

called for protocol templates.

1033

1034

1035

<HR><H3>Function</H3>

1036

1037

<B>protos_commit</B>

1038

(<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>, <I>int</I> <B>force_reconfig</B>, <I>int</I> <B>type</B>) -- commit new protocol configuration

1039

<P>

1040

<H3>Arguments</H3>

1041

<P>

1042

<DL>

1043

<DT><I>struct config *</I> <B>new</B><DD><P>new configuration

1044

<DT><I>struct config *</I> <B>old</B><DD><P>old configuration or <I>NULL</I> if it's boot time config

1045

<DT><I>int</I> <B>force_reconfig</B><DD><P>force restart of all protocols (used for example

1046

when the router ID changes)

1047

<DT><I>int</I> <B>type</B><DD><P>type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)

1048

</DL>

1049

<H3>Description</H3>

1050

<P>Scan differences between <B>old</B> and <B>new</B> configuration and adjust all

1051

protocol instances to conform to the new configuration.

1052

<P>When a protocol exists in the new configuration, but it doesn't in the

1053

original one, it's immediately started. When a collision with the other

1054

running protocol would arise, the new protocol will be temporarily stopped

1055

by the locking mechanism.

1056

<P>When a protocol exists in the old configuration, but it doesn't in the

1057

new one, it's shut down and deleted after the shutdown completes.

1058

<P>When a protocol exists in both configurations, the core decides

1059

whether it's possible to reconfigure it dynamically - it checks all

1060

the core properties of the protocol (changes in filters are ignored

1061

if type is RECONFIG_SOFT) and if they match, it asks the

1062

<B>reconfigure()</B> hook of the protocol to see if the protocol is able

1063

to switch to the new configuration. If it isn't possible, the

1064

protocol is shut down and a new instance is started with the new

1065

configuration after the shutdown is completed.

1066

1067

1068

<HR><H3>Function</H3>

1069

1070

<B>protos_dump_all</B>

1071

(<B>void</B>) -- dump status of all protocols

1072

<P>

1073

<H3>Description</H3>

1074

<P>

1075

<P>This function dumps status of all existing protocol instances to the

1076

debug output. It involves printing of general status information

1077

such as protocol states, its position on the protocol lists

1078

and also calling of a <B>dump()</B> hook of the protocol to print

1079

the internals.

1080

1081

1082

<HR><H3>Function</H3>

1083

1084

<B>proto_build</B>

1085

(<I>struct protocol *</I> <B>p</B>) -- make a single protocol available

1086

<P>

1087

<H3>Arguments</H3>

1088

<P>

1089

<DL>

1090

<DT><I>struct protocol *</I> <B>p</B><DD><P>the protocol

1091

</DL>

1092

<H3>Description</H3>

1093

<P>After the platform specific initialization code uses <B>protos_build()</B>

1094

to add all the standard protocols, it should call <B>proto_build()</B> for

1095

all platform specific protocols to inform the core that they exist.

1096

1097

1098

<HR><H3>Function</H3>

1099

1100

<B>protos_build</B>

1101

(<B>void</B>) -- build a protocol list

1102

<P>

1103

<H3>Description</H3>

1104

<P>

1105

<P>This function is called during BIRD startup to insert

1106

all standard protocols to the global protocol list. Insertion

1107

of platform specific protocols (such as the kernel syncer)

1108

is in the domain of competence of the platform dependent

1109

startup code.

1110

1111

1112

<HR><H3>Function</H3>

1113

1114

<B>proto_request_feeding</B>

1115

(<I>struct proto *</I> <B>p</B>) -- request feeding routes to the protocol

1116

<P>

1117

<H3>Arguments</H3>

1118

<P>

1119

<DL>

1120

<DT><I>struct proto *</I> <B>p</B><DD><P>given protocol

1121

</DL>

1122

<H3>Description</H3>

1123

<P>Sometimes it is needed to send again all routes to the

1124

protocol. This is called feeding and can be requested by this

1125

function. This would cause protocol core state transition

1126

to FS_FEEDING (during feeding) and when completed, it will

1127

switch back to FS_HAPPY. This function can be called even

1128

when feeding is already running, in that case it is restarted.

1129

1130

1131

<HR><H3>Function</H3>

1132

1133

<B>proto_notify_limit</B>

1134

(<I>struct announce_hook *</I> <B>ah</B>, <I>struct proto_limit *</I> <B>l</B>, <I>int</I> <B>dir</B>, <I>u32</I> <B>rt_count</B>)

1135

<H3>Arguments</H3>

1136

<P>

1137

<DL>

1138

<DT><I>struct announce_hook *</I> <B>ah</B><DD><P>announce hook

1139

<DT><I>struct proto_limit *</I> <B>l</B><DD><P>limit being hit

1140

<DT><I>int</I> <B>dir</B><DD><P>limit direction (PLD_*)

1141

<DT><I>u32</I> <B>rt_count</B><DD><P>the number of routes

1142

</DL>

1143

<H3>Description</H3>

1144

<P>The function is called by the route processing core when limit <B>l</B>

1145

is breached. It activates the limit and tooks appropriate action

1146

according to <B>l</B>->action.

1147

1148

1149

<HR><H3>Function</H3>

1150

1151

<B>proto_notify_state</B>

1152

(<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>ps</B>) -- notify core about protocol state change

1153

<P>

1154

<H3>Arguments</H3>

1155

<P>

1156

<DL>

1157

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol the state of which has changed

1158

<DT><I>unsigned</I> <B>ps</B><DD><P>the new status

1159

</DL>

1160

<H3>Description</H3>

1161

<P>Whenever a state of a protocol changes due to some event internal

1162

to the protocol (i.e., not inside a <B>start()</B> or <B>shutdown()</B> hook),

1163

it should immediately notify the core about the change by calling

1164

<B>proto_notify_state()</B> which will write the new state to the <I>proto</I>

1165

structure and take all the actions necessary to adapt to the new

1166

state. State change to PS_DOWN immediately frees resources of protocol

1167

and might execute start callback of protocol; therefore,

1168

it should be used at tail positions of protocol callbacks.

1169

1170

<H2><A NAME="ss2.5">2.5</A> <A HREF="prog.html#toc2.5">Protocol hooks</A>

1171

</H2>

1172

1173

<P>

1174

<P>Each protocol can provide a rich set of hook functions referred to by pointers

1175

in either the <I>proto</I> or <I>protocol</I> structure. They are called by the core whenever

1176

it wants the protocol to perform some action or to notify the protocol about

1177

any change of its environment. All of the hooks can be set to <I>NULL</I> which means

1178

to ignore the change or to take a default action.

1179

<P>

1180

<P><HR><H3>Function</H3>

1181

1182

<B>preconfig</B>

1183

(<I>struct protocol *</I> <B>p</B>, <I>struct config *</I> <B>c</B>) -- protocol preconfiguration

1184

<P>

1185

<H3>Arguments</H3>

1186

<P>

1187

<DL>

1188

<DT><I>struct protocol *</I> <B>p</B><DD><P>a routing protocol

1189

<DT><I>struct config *</I> <B>c</B><DD><P>new configuration

1190

</DL>

1191

<H3>Description</H3>

1192

<P>The <B>preconfig()</B> hook is called before parsing of a new configuration.

1193

1194

1195

<HR><H3>Function</H3>

1196

1197

<B>postconfig</B>

1198

(<I>struct proto_config *</I> <B>c</B>) -- instance post-configuration

1199

<P>

1200

<H3>Arguments</H3>

1201

<P>

1202

<DL>

1203

<DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration

1204

</DL>

1205

<H3>Description</H3>

1206

<P>The <B>postconfig()</B> hook is called for each configured instance after

1207

parsing of the new configuration is finished.

1208

1209

1210

<HR><H3>Function</H3>

1211

<P><I>struct proto *</I>

1212

1213

(<I>struct proto_config *</I> <B>c</B>) -- initialize an instance

1214

<P>

1215

<H3>Arguments</H3>

1216

<P>

1217

<DL>

1218

<DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration

1219

</DL>

1220

<H3>Description</H3>

1221

<P>The <B>init()</B> hook is called by the core to create a protocol instance

1222

according to supplied protocol configuration.

1223

<H3>Result</H3>

1224

<P>a pointer to the instance created

1225

1226

1227

<HR><H3>Function</H3>

1228

1229

<B>reconfigure</B>

1230

(<I>struct proto *</I> <B>p</B>, <I>struct proto_config *</I> <B>c</B>) -- request instance reconfiguration

1231

<P>

1232

<H3>Arguments</H3>

1233

<P>

1234

<DL>

1235

<DT><I>struct proto *</I> <B>p</B><DD><P>an instance

1236

<DT><I>struct proto_config *</I> <B>c</B><DD><P>new configuration

1237

</DL>

1238

<H3>Description</H3>

1239

<P>The core calls the <B>reconfigure()</B> hook whenever it wants to ask the

1240

protocol for switching to a new configuration. If the reconfiguration

1241

is possible, the hook returns 1. Otherwise, it returns 0 and the core

1242

will shut down the instance and start a new one with the new configuration.

1243

<P>After the protocol confirms reconfiguration, it must no longer keep any

1244

references to the old configuration since the memory it's stored in can

1245

be re-used at any time.

1246

1247

1248

<HR><H3>Function</H3>

1249

1250

1251

(<I>struct proto *</I> <B>p</B>) -- dump protocol state

1252

<P>

1253

<H3>Arguments</H3>

1254

<P>

1255

<DL>

1256

<DT><I>struct proto *</I> <B>p</B><DD><P>an instance

1257

</DL>

1258

<H3>Description</H3>

1259

<P>This hook dumps the complete state of the instance to the

1260

debug output.

1261

1262

1263

<HR><H3>Function</H3>

1264

1265

<B>dump_attrs</B>

1266

(<I>rte *</I> <B>e</B>) -- dump protocol-dependent attributes

1267

<P>

1268

<H3>Arguments</H3>

1269

<P>

1270

<DL>

1271

<DT><I>rte *</I> <B>e</B><DD><P>a route entry

1272

</DL>

1273

<H3>Description</H3>

1274

<P>This hook dumps all attributes in the <I>rte</I> which belong to this

1275

protocol to the debug output.

1276

1277

1278

<HR><H3>Function</H3>

1279

1280

<B>start</B>

1281

(<I>struct proto *</I> <B>p</B>) -- request instance startup

1282

<P>

1283

<H3>Arguments</H3>

1284

<P>

1285

<DL>

1286

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1287

</DL>

1288

<H3>Description</H3>

1289

<P>The <B>start()</B> hook is called by the core when it wishes to start

1290

the instance. Multitable protocols should lock their tables here.

1291

<H3>Result</H3>

1292

<P>new protocol state

1293

1294

1295

<HR><H3>Function</H3>

1296

1297

<B>shutdown</B>

1298

(<I>struct proto *</I> <B>p</B>) -- request instance shutdown

1299

<P>

1300

<H3>Arguments</H3>

1301

<P>

1302

<DL>

1303

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1304

</DL>

1305

<H3>Description</H3>

1306

<P>The <B>stop()</B> hook is called by the core when it wishes to shut

1307

the instance down for some reason.

1308

<H3>Returns</H3>

1309

<P>new protocol state

1310

1311

1312

<HR><H3>Function</H3>

1313

1314

<B>cleanup</B>

1315

(<I>struct proto *</I> <B>p</B>) -- request instance cleanup

1316

<P>

1317

<H3>Arguments</H3>

1318

<P>

1319

<DL>

1320

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1321

</DL>

1322

<H3>Description</H3>

1323

<P>The <B>cleanup()</B> hook is called by the core when the protocol became

1324

hungry/down, i.e. all protocol ahooks and routes are flushed.

1325

Multitable protocols should unlock their tables here.

1326

1327

1328

<HR><H3>Function</H3>

1329

1330

<B>get_status</B>

1331

(<I>struct proto *</I> <B>p</B>, <I>byte *</I> <B>buf</B>) -- get instance status

1332

<P>

1333

<H3>Arguments</H3>

1334

<P>

1335

<DL>

1336

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1337

<DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the status string

1338

</DL>

1339

<H3>Description</H3>

1340

<P>This hook is called by the core if it wishes to obtain an brief one-line user friendly

1341

representation of the status of the instance to be printed by the <cf/show protocols/

1342

command.

1343

1344

1345

<HR><H3>Function</H3>

1346

1347

<B>get_route_info</B>

1348

(<I>rte *</I> <B>e</B>, <I>byte *</I> <B>buf</B>, <I>ea_list *</I> <B>attrs</B>) -- get route information

1349

<P>

1350

<H3>Arguments</H3>

1351

<P>

1352

<DL>

1353

<DT><I>rte *</I> <B>e</B><DD><P>a route entry

1354

<DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the resulting string

1355

<DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes of the route

1356

</DL>

1357

<H3>Description</H3>

1358

<P>This hook is called to fill the buffer <B>buf</B> with a brief user friendly

1359

representation of metrics of a route belonging to this protocol.

1360

1361

1362

<HR><H3>Function</H3>

1363

1364

1365

(<I>eattr *</I> <B>a</B>, <I>byte *</I> <B>buf</B>, <I>int</I> <B>buflen</B>) -- get attribute information

1366

<P>

1367

<H3>Arguments</H3>

1368

<P>

1369

<DL>

1370

<DT><I>eattr *</I> <B>a</B><DD><P>an extended attribute

1371

<DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with attribute information

1372

<DT><I>int</I> <B>buflen</B><DD><P>-- undescribed --

1373

</DL>

1374

<H3>Description</H3>

1375

<P>The <B>get_attr()</B> hook is called by the core to obtain a user friendly

1376

representation of an extended route attribute. It can either leave

1377

the whole conversion to the core (by returning <I>GA_UNKNOWN</I>), fill

1378

in only attribute name (and let the core format the attribute value

1379

automatically according to the type field; by returning <I>GA_NAME</I>)

1380

or doing the whole conversion (used in case the value requires extra

1381

care; return <I>GA_FULL</I>).

1382

1383

1384

<HR><H3>Function</H3>

1385

1386

<B>if_notify</B>

1387

(<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct iface *</I> <B>i</B>) -- notify instance about interface changes

1388

<P>

1389

<H3>Arguments</H3>

1390

<P>

1391

<DL>

1392

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1393

<DT><I>unsigned</I> <B>flags</B><DD><P>interface change flags

1394

<DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question

1395

</DL>

1396

<H3>Description</H3>

1397

<P>This hook is called whenever any network interface changes its status.

1398

The change is described by a combination of status bits (<I>IF_CHANGE_xxx</I>)

1399

in the <B>flags</B> parameter.

1400

1401

1402

<HR><H3>Function</H3>

1403

1404

<B>ifa_notify</B>

1405

(<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct ifa *</I> <B>a</B>) -- notify instance about interface address changes

1406

<P>

1407

<H3>Arguments</H3>

1408

<P>

1409

<DL>

1410

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1411

<DT><I>unsigned</I> <B>flags</B><DD><P>address change flags

1412

<DT><I>struct ifa *</I> <B>a</B><DD><P>the interface address

1413

</DL>

1414

<H3>Description</H3>

1415

<P>This hook is called to notify the protocol instance about an interface

1416

acquiring or losing one of its addresses. The change is described by

1417

a combination of status bits (<I>IF_CHANGE_xxx</I>) in the <B>flags</B> parameter.

1418

1419

1420

<HR><H3>Function</H3>

1421

1422

<B>rt_notify</B>

1423

(<I>struct proto *</I> <B>p</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>ea_list *</I> <B>attrs</B>) -- notify instance about routing table change

1424

<P>

1425

<H3>Arguments</H3>

1426

<P>

1427

<DL>

1428

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance

1429

<DT><I>net *</I> <B>net</B><DD><P>a network entry

1430

<DT><I>rte *</I> <B>new</B><DD><P>new route for the network

1431

<DT><I>rte *</I> <B>old</B><DD><P>old route for the network

1432

<DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes associated with the <B>new</B> entry

1433

</DL>

1434

<H3>Description</H3>

1435

<P>The <B>rt_notify()</B> hook is called to inform the protocol instance about

1436

changes in the connected routing table <B>table</B>, that is a route <B>old</B>

1437

belonging to network <B>net</B> being replaced by a new route <B>new</B> with

1438

extended attributes <B>attrs</B>. Either <B>new</B> or <B>old</B> or both can be <I>NULL</I>

1439

if the corresponding route doesn't exist.

1440

<P>If the type of route announcement is RA_OPTIMAL, it is an

1441

announcement of optimal route change, <B>new</B> stores the new optimal

1442

route and <B>old</B> stores the old optimal route.

1443

<P>If the type of route announcement is RA_ANY, it is an announcement

1444

of any route change, <B>new</B> stores the new route and <B>old</B> stores the

1445

old route from the same protocol.

1446

<P><B>p</B>->accept_ra_types specifies which kind of route announcements

1447

protocol wants to receive.

1448

1449

1450

<HR><H3>Function</H3>

1451

1452

<B>neigh_notify</B>

1453

(<I>neighbor *</I> <B>neigh</B>) -- notify instance about neighbor status change

1454

<P>

1455

<H3>Arguments</H3>

1456

<P>

1457

<DL>

1458

<DT><I>neighbor *</I> <B>neigh</B><DD><P>a neighbor cache entry

1459

</DL>

1460

<H3>Description</H3>

1461

<P>The <B>neigh_notify()</B> hook is called by the neighbor cache whenever

1462

a neighbor changes its state, that is it gets disconnected or a

1463

sticky neighbor gets connected.

1464

1465

1466

<HR><H3>Function</H3>

1467

1468

<B>make_tmp_attrs</B>

1469

(<I>rte *</I> <B>e</B>, <I>struct linpool *</I> <B>pool</B>) -- convert embedded attributes to temporary ones

1470

<P>

1471

<H3>Arguments</H3>

1472

<P>

1473

<DL>

1474

<DT><I>rte *</I> <B>e</B><DD><P>route entry

1475

<DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool to allocate attribute memory in

1476

</DL>

1477

<H3>Description</H3>

1478

<P>This hook is called by the routing table functions if they need

1479

to convert the protocol attributes embedded directly in the <I>rte</I>

1480

to temporary extended attributes in order to distribute them

1481

to other protocols or to filters. <B>make_tmp_attrs()</B> creates

1482

an <I>ea_list</I> in the linear pool <B>pool</B>, fills it with values of the

1483

temporary attributes and returns a pointer to it.

1484

1485

1486

<HR><H3>Function</H3>

1487

1488

<B>store_tmp_attrs</B>

1489

(<I>rte *</I> <B>e</B>, <I>ea_list *</I> <B>attrs</B>) -- convert temporary attributes to embedded ones

1490

<P>

1491

<H3>Arguments</H3>

1492

<P>

1493

<DL>

1494

<DT><I>rte *</I> <B>e</B><DD><P>route entry

1495

<DT><I>ea_list *</I> <B>attrs</B><DD><P>temporary attributes to be converted

1496

</DL>

1497

<H3>Description</H3>

1498

<P>This hook is an exact opposite of <B>make_tmp_attrs()</B> -- it takes

1499

a list of extended attributes and converts them to attributes

1500

embedded in the <I>rte</I> corresponding to this protocol.

1501

<P>You must be prepared for any of the attributes being missing

1502

from the list and use default values instead.

1503

1504

1505

<HR><H3>Function</H3>

1506

1507

<B>import_control</B>

1508

(<I>struct proto *</I> <B>p</B>, <I>rte **</I> <B>e</B>, <I>ea_list **</I> <B>attrs</B>, <I>struct linpool *</I> <B>pool</B>) -- pre-filtering decisions on route import

1509

<P>

1510

<H3>Arguments</H3>

1511

<P>

1512

<DL>

1513

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance the route is going to be imported to

1514

<DT><I>rte **</I> <B>e</B><DD><P>the route in question

1515

<DT><I>ea_list **</I> <B>attrs</B><DD><P>extended attributes of the route

1516

<DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool for allocation of all temporary data

1517

</DL>

1518

<H3>Description</H3>

1519

<P>The <B>import_control()</B> hook is called as the first step of a exporting

1520

a route from a routing table to the protocol instance. It can modify

1521

route attributes and force acceptance or rejection of the route regardless

1522

of user-specified filters. See <B>rte_announce()</B> for a complete description

1523

of the route distribution process.

1524

<P>The standard use of this hook is to reject routes having originated

1525

from the same instance and to set default values of the protocol's metrics.

1526

<H3>Result</H3>

1527

<P>1 if the route has to be accepted, -1 if rejected and 0 if it

1528

should be passed to the filters.

1529

1530

1531

<HR><H3>Function</H3>

1532

1533

<B>rte_recalculate</B>

1534

(<I>struct rtable *</I> <B>table</B>, <I>struct network *</I> <B>net</B>, <I>struct rte *</I> <B>new</B>, <I>struct rte *</I> <B>old</B>, <I>struct rte *</I> <B>old_best</B>) -- prepare routes for comparison

1535

<P>

1536

<H3>Arguments</H3>

1537

<P>

1538

<DL>

1539

<DT><I>struct rtable *</I> <B>table</B><DD><P>a routing table

1540

<DT><I>struct network *</I> <B>net</B><DD><P>a network entry

1541

<DT><I>struct rte *</I> <B>new</B><DD><P>new route for the network

1542

<DT><I>struct rte *</I> <B>old</B><DD><P>old route for the network

1543

<DT><I>struct rte *</I> <B>old_best</B><DD><P>old best route for the network (may be NULL)

1544

</DL>

1545

<H3>Description</H3>

1546

<P>This hook is called when a route change (from <B>old</B> to <B>new</B> for a

1547

<B>net</B> entry) is propagated to a <B>table</B>. It may be used to prepare

1548

routes for comparison by <B>rte_better()</B> in the best route

1549

selection. <B>new</B> may or may not be in <B>net</B>->routes list,

1550

<B>old</B> is not there.

1551

<H3>Result</H3>

1552

<P>1 if the ordering implied by <B>rte_better()</B> changes enough

1553

that full best route calculation have to be done, 0 otherwise.

1554

1555

1556

<HR><H3>Function</H3>

1557

1558

<B>rte_better</B>

1559

(<I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>) -- compare metrics of two routes

1560

<P>

1561

<H3>Arguments</H3>

1562

<P>

1563

<DL>

1564

<DT><I>rte *</I> <B>new</B><DD><P>the new route

1565

<DT><I>rte *</I> <B>old</B><DD><P>the original route

1566

</DL>

1567

<H3>Description</H3>

1568

<P>This hook gets called when the routing table contains two routes

1569

for the same network which have originated from different instances

1570

of a single protocol and it wants to select which one is preferred

1571

over the other one. Protocols usually decide according to route metrics.

1572

<H3>Result</H3>

1573

<P>1 if <B>new</B> is better (more preferred) than <B>old</B>, 0 otherwise.

1574

1575

1576

<HR><H3>Function</H3>

1577

1578

1579

(<I>rte *</I> <B>e1</B>, <I>rte *</I> <B>e2</B>) -- compare two routes

1580

<P>

1581

<H3>Arguments</H3>

1582

<P>

1583

<DL>

1584

<DT><I>rte *</I> <B>e1</B><DD><P>route

1585

<DT><I>rte *</I> <B>e2</B><DD><P>route

1586

</DL>

1587

<H3>Description</H3>

1588

<P>The <B>rte_same()</B> hook tests whether the routes <B>e1</B> and <B>e2</B> belonging

1589

to the same protocol instance have identical contents. Contents of

1590

<I>rta</I>, all the extended attributes and <I>rte</I> preference are checked

1591

by the core code, no need to take care of them here.

1592

<H3>Result</H3>

1593

<P>1 if <B>e1</B> is identical to <B>e2</B>, 0 otherwise.

1594

1595

1596

<HR><H3>Function</H3>

1597

1598

<B>rte_insert</B>

1599

(<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) -- notify instance about route insertion

1600

<P>

1601

<H3>Arguments</H3>

1602

<P>

1603

<DL>

1604

<DT><I>net *</I> <B>n</B><DD><P>network

1605

<DT><I>rte *</I> <B>e</B><DD><P>route

1606

</DL>

1607

<H3>Description</H3>

1608

<P>This hook is called whenever a <I>rte</I> belonging to the instance

1609

is accepted for insertion to a routing table.

1610

<P>Please avoid using this function in new protocols.

1611

1612

1613

<HR><H3>Function</H3>

1614

1615

<B>rte_remove</B>

1616

(<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) -- notify instance about route removal

1617

<P>

1618

<H3>Arguments</H3>

1619

<P>

1620

<DL>

1621

<DT><I>net *</I> <B>n</B><DD><P>network

1622

<DT><I>rte *</I> <B>e</B><DD><P>route

1623

</DL>

1624

<H3>Description</H3>

1625

<P>This hook is called whenever a <I>rte</I> belonging to the instance

1626

is removed from a routing table.

1627

<P>Please avoid using this function in new protocols.

1628

1629

<H2><A NAME="ss2.6">2.6</A> <A HREF="prog.html#toc2.6">Interfaces</A>

1630

</H2>

1631

1632

<P>

1633

<P>The interface module keeps track of all network interfaces in the

1634

system and their addresses.

1635

<P>Each interface is represented by an <I>iface</I> structure which carries

1636

interface capability flags (<I>IF_MULTIACCESS</I>, <I>IF_BROADCAST</I> etc.),

1637

MTU, interface name and index and finally a linked list of network

1638

prefixes assigned to the interface, each one represented by

1639

struct <I>ifa</I>.

1640

<P>The interface module keeps a `soft-up' state for each <I>iface</I> which

1641

is a conjunction of link being up, the interface being of a `sane'

1642

type and at least one IP address assigned to it.

1643

<P>

1644

<P><HR><H3>Function</H3>

1645

1646

1647

(<I>struct ifa *</I> <B>a</B>) -- dump interface address

1648

<P>

1649

<H3>Arguments</H3>

1650

<P>

1651

<DL>

1652

<DT><I>struct ifa *</I> <B>a</B><DD><P>interface address descriptor

1653

</DL>

1654

<H3>Description</H3>

1655

<P>This function dumps contents of an <I>ifa</I> to the debug output.

1656

1657

1658

<HR><H3>Function</H3>

1659

1660

1661

(<I>struct iface *</I> <B>i</B>) -- dump interface

1662

<P>

1663

<H3>Arguments</H3>

1664

<P>

1665

<DL>

1666

<DT><I>struct iface *</I> <B>i</B><DD><P>interface to dump

1667

</DL>

1668

<H3>Description</H3>

1669

<P>This function dumps all information associated with a given

1670

network interface to the debug output.

1671

1672

1673

<HR><H3>Function</H3>

1674

1675

1676

(<B>void</B>) -- dump all interfaces

1677

<P>

1678

<H3>Description</H3>

1679

<P>

1680

<P>This function dumps information about all known network

1681

interfaces to the debug output.

1682

1683

1684

<HR><H3>Function</H3>

1685

1686

<B>if_delete</B>

1687

(<I>struct iface *</I> <B>old</B>) -- remove interface

1688

<P>

1689

<H3>Arguments</H3>

1690

<P>

1691

<DL>

1692

<DT><I>struct iface *</I> <B>old</B><DD><P>interface

1693

</DL>

1694

<H3>Description</H3>

1695

<P>This function is called by the low-level platform dependent code

1696

whenever it notices an interface disappears. It is just a shorthand

1697

for <B>if_update()</B>.

1698

1699

1700

<HR><H3>Function</H3>

1701

<P><I>struct iface *</I>

1702

<B>if_update</B>

1703

(<I>struct iface *</I> <B>new</B>) -- update interface status

1704

<P>

1705

<H3>Arguments</H3>

1706

<P>

1707

<DL>

1708

<DT><I>struct iface *</I> <B>new</B><DD><P>new interface status

1709

</DL>

1710

<H3>Description</H3>

1711

<P><B>if_update()</B> is called by the low-level platform dependent code

1712

whenever it notices an interface change.

1713

<P>There exist two types of interface updates -- synchronous and asynchronous

1714

ones. In the synchronous case, the low-level code calls <B>if_start_update()</B>,

1715

scans all interfaces reported by the OS, uses <B>if_update()</B> and <B>ifa_update()</B>

1716

to pass them to the core and then it finishes the update sequence by

1717

calling <B>if_end_update()</B>. When working asynchronously, the sysdep code

1718

calls <B>if_update()</B> and <B>ifa_update()</B> whenever it notices a change.

1719

<P><B>if_update()</B> will automatically notify all other modules about the change.

1720

1721

1722

<HR><H3>Function</H3>

1723

1724

1725

(<I>struct proto *</I> <B>p</B>) -- advertise interfaces to a new protocol

1726

<P>

1727

<H3>Arguments</H3>

1728

<P>

1729

<DL>

1730

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol to feed

1731

</DL>

1732

<H3>Description</H3>

1733

<P>When a new protocol starts, this function sends it a series

1734

of notifications about all existing interfaces.

1735

1736

1737

<HR><H3>Function</H3>

1738

<P><I>struct iface *</I>

1739

<B>if_find_by_index</B>

1740

(<I>unsigned</I> <B>idx</B>) -- find interface by ifindex

1741

<P>

1742

<H3>Arguments</H3>

1743

<P>

1744

<DL>

1745

<DT><I>unsigned</I> <B>idx</B><DD><P>ifindex

1746

</DL>

1747

<H3>Description</H3>

1748

<P>This function finds an <I>iface</I> structure corresponding to an interface

1749

of the given index <B>idx</B>. Returns a pointer to the structure or <I>NULL</I>

1750

if no such structure exists.

1751

1752

1753

<HR><H3>Function</H3>

1754

<P><I>struct iface *</I>

1755

1756

(<I>char *</I> <B>name</B>) -- find interface by name

1757

<P>

1758

<H3>Arguments</H3>

1759

<P>

1760

<DL>

1761

<DT><I>char *</I> <B>name</B><DD><P>interface name

1762

</DL>

1763

<H3>Description</H3>

1764

<P>This function finds an <I>iface</I> structure corresponding to an interface

1765

of the given name <B>name</B>. Returns a pointer to the structure or <I>NULL</I>

1766

if no such structure exists.

1767

1768

1769

<HR><H3>Function</H3>

1770

<P><I>struct ifa *</I>

1771

<B>ifa_update</B>

1772

(<I>struct ifa *</I> <B>a</B>) -- update interface address

1773

<P>

1774

<H3>Arguments</H3>

1775

<P>

1776

<DL>

1777

<DT><I>struct ifa *</I> <B>a</B><DD><P>new interface address

1778

</DL>

1779

<H3>Description</H3>

1780

<P>This function adds address information to a network

1781

interface. It's called by the platform dependent code during

1782

the interface update process described under <B>if_update()</B>.

1783

1784

1785

<HR><H3>Function</H3>

1786

1787

<B>ifa_delete</B>

1788

(<I>struct ifa *</I> <B>a</B>) -- remove interface address

1789

<P>

1790

<H3>Arguments</H3>

1791

<P>

1792

<DL>

1793

<DT><I>struct ifa *</I> <B>a</B><DD><P>interface address

1794

</DL>

1795

<H3>Description</H3>

1796

<P>This function removes address information from a network

1797

interface. It's called by the platform dependent code during

1798

the interface update process described under <B>if_update()</B>.

1799

1800

1801

<HR><H3>Function</H3>

1802

1803

1804

(<B>void</B>) -- initialize interface module

1805

<P>

1806

<H3>Description</H3>

1807

<P>

1808

<P>This function is called during BIRD startup to initialize

1809

all data structures of the interface module.

1810

1811

<H2><A NAME="ss2.7">2.7</A> <A HREF="prog.html#toc2.7">Neighbor cache</A>

1812

</H2>

1813

1814

<P>

1815

<P>Most routing protocols need to associate their internal state data with

1816

neighboring routers, check whether an address given as the next hop

1817

attribute of a route is really an address of a directly connected host

1818

and which interface is it connected through. Also, they often need to

1819

be notified when a neighbor ceases to exist or when their long awaited

1820

neighbor becomes connected. The neighbor cache is there to solve all

1821

these problems.

1822

<P>The neighbor cache maintains a collection of neighbor entries. Each

1823

entry represents one IP address corresponding to either our directly

1824

connected neighbor or our own end of the link (when the scope of the

1825

address is set to <I>SCOPE_HOST</I>) together with per-neighbor data belonging to a

1826

single protocol.

1827

<P>Active entries represent known neighbors and are stored in a hash

1828

table (to allow fast retrieval based on the IP address of the node) and

1829

two linked lists: one global and one per-interface (allowing quick

1830

processing of interface change events). Inactive entries exist only

1831

when the protocol has explicitly requested it via the <I>NEF_STICKY</I>

1832

flag because it wishes to be notified when the node will again become

1833

a neighbor. Such entries are enqueued in a special list which is walked

1834

whenever an interface changes its state to up.

1835

<P>When a neighbor event occurs (a neighbor gets disconnected or a sticky

1836

inactive neighbor becomes connected), the protocol hook <B>neigh_notify()</B>

1837

is called to advertise the change.

1838

<P>

1839

<P><HR><H3>Function</H3>

1840

<P><I>neighbor *</I>

1841

<B>neigh_find</B>

1842

(<I>struct proto *</I> <B>p</B>, <I>ip_addr *</I> <B>a</B>, <I>unsigned</I> <B>flags</B>) -- find or create a neighbor entry.

1843

<P>

1844

<H3>Arguments</H3>

1845

<P>

1846

<DL>

1847

<DT><I>struct proto *</I> <B>p</B><DD><P>protocol which asks for the entry.

1848

<DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the node to be searched for.

1849

<DT><I>unsigned</I> <B>flags</B><DD><P>0 or <I>NEF_STICKY</I> if you want to create a sticky entry.

1850

</DL>

1851

<H3>Description</H3>

1852

<P>Search the neighbor cache for a node with given IP address. If

1853

it's found, a pointer to the neighbor entry is returned. If no

1854

such entry exists and the node is directly connected on

1855

one of our active interfaces, a new entry is created and returned

1856

to the caller with protocol-dependent fields initialized to zero.

1857

If the node is not connected directly or *<B>a</B> is not a valid unicast

1858

IP address, <B>neigh_find()</B> returns <I>NULL</I>.

1859

1860

1861

<HR><H3>Function</H3>

1862

1863

<B>neigh_dump</B>

1864

(<I>neighbor *</I> <B>n</B>) -- dump specified neighbor entry.

1865

<P>

1866

<H3>Arguments</H3>

1867

<P>

1868

<DL>

1869

<DT><I>neighbor *</I> <B>n</B><DD><P>the entry to dump

1870

</DL>

1871

<H3>Description</H3>

1872

<P>This functions dumps the contents of a given neighbor entry

1873

to debug output.

1874

1875

1876

<HR><H3>Function</H3>

1877

1878

<B>neigh_dump_all</B>

1879

(<B>void</B>) -- dump all neighbor entries.

1880

<P>

1881

<H3>Description</H3>

1882

<P>

1883

<P>This function dumps the contents of the neighbor cache to

1884

debug output.

1885

1886

1887

<HR><H3>Function</H3>

1888

1889

<B>neigh_if_up</B>

1890

(<I>struct iface *</I> <B>i</B>)

1891

<H3>Arguments</H3>

1892

<P>

1893

<DL>

1894

<DT><I>struct iface *</I> <B>i</B><DD><P>interface in question

1895

</DL>

1896

<H3>Description</H3>

1897

<P>Tell the neighbor cache that a new interface became up.

1898

<P>The neighbor cache wakes up all inactive sticky neighbors with

1899

addresses belonging to prefixes of the interface <B>i</B>.

1900

1901

1902

<HR><H3>Function</H3>

1903

1904

<B>neigh_if_down</B>

1905

(<I>struct iface *</I> <B>i</B>) -- notify neighbor cache about interface down event

1906

<P>

1907

<H3>Arguments</H3>

1908

<P>

1909

<DL>

1910

<DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question

1911

</DL>

1912

<H3>Description</H3>

1913

<P>Notify the neighbor cache that an interface has ceased to exist.

1914

<P>It causes all entries belonging to neighbors connected to this interface

1915

to be flushed.

1916

1917

1918

<HR><H3>Function</H3>

1919

1920

<B>neigh_if_link</B>

1921

(<I>struct iface *</I> <B>i</B>) -- notify neighbor cache about interface link change

1922

<P>

1923

<H3>Arguments</H3>

1924

<P>

1925

<DL>

1926

<DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question

1927

</DL>

1928

<H3>Description</H3>

1929

<P>Notify the neighbor cache that an interface changed link state.

1930

All owners of neighbor entries connected to this interface are

1931

notified.

1932

1933

1934

<HR><H3>Function</H3>

1935

1936

<B>neigh_ifa_update</B>

1937

(<I>struct ifa *</I> <B>a</B>)

1938

<H3>Arguments</H3>

1939

<P>

1940

<DL>

1941

<DT><I>struct ifa *</I> <B>a</B><DD><P>-- undescribed --

1942

</DL>

1943

<H3>Description</H3>

1944

<P>Tell the neighbor cache that an address was added or removed.

1945

<P>The neighbor cache wakes up all inactive sticky neighbors with

1946

addresses belonging to prefixes of the interface belonging to <B>ifa</B>

1947

and causes all unreachable neighbors to be flushed.

1948

1949

1950

<HR><H3>Function</H3>

1951

1952

<B>neigh_prune</B>

1953

(<B>void</B>) -- prune neighbor cache

1954

<P>

1955

<H3>Description</H3>

1956

<P>

1957

<P><B>neigh_prune()</B> examines all neighbor entries cached and removes those

1958

corresponding to inactive protocols. It's called whenever a protocol

1959

is shut down to get rid of all its heritage.

1960

1961

1962

<HR><H3>Function</H3>

1963

1964

<B>neigh_init</B>

1965

(<I>pool *</I> <B>if_pool</B>) -- initialize the neighbor cache.

1966

<P>

1967

<H3>Arguments</H3>

1968

<P>

1969

<DL>

1970

<DT><I>pool *</I> <B>if_pool</B><DD><P>resource pool to be used for neighbor entries.

1971

</DL>

1972

<H3>Description</H3>

1973

<P>This function is called during BIRD startup to initialize

1974

the neighbor cache module.

1975

1976

<H2><A NAME="ss2.8">2.8</A> <A HREF="prog.html#toc2.8">Command line interface</A>

1977

</H2>

1978

1979

<P>

1980

<P>This module takes care of the BIRD's command-line interface (CLI).

1981

The CLI exists to provide a way to control BIRD remotely and to inspect

1982

its status. It uses a very simple textual protocol over a stream

1983

connection provided by the platform dependent code (on UNIX systems,

1984

it's a UNIX domain socket).

1985

<P>Each session of the CLI consists of a sequence of request and replies,

1986

slightly resembling the FTP and SMTP protocols.

1987

Requests are commands encoded as a single line of text, replies are

1988

sequences of lines starting with a four-digit code followed by either

1989

a space (if it's the last line of the reply) or a minus sign (when the

1990

reply is going to continue with the next line), the rest of the line

1991

contains a textual message semantics of which depends on the numeric

1992

code. If a reply line has the same code as the previous one and it's

1993

a continuation line, the whole prefix can be replaced by a single

1994

white space character.

1995

<P>Reply codes starting with 0 stand for `action successfully completed' messages,

1996

1 means `table entry', 8 `runtime error' and 9 `syntax error'.

1997

<P>Each CLI session is internally represented by a <I>cli</I> structure and a

1998

resource pool containing all resources associated with the connection,

1999

so that it can be easily freed whenever the connection gets closed, not depending

2000

on the current state of command processing.

2001

<P>The CLI commands are declared as a part of the configuration grammar

2002

by using the <CODE>CF_CLI</CODE> macro. When a command is received, it is processed

2003

by the same lexical analyzer and parser as used for the configuration, but

2004

it's switched to a special mode by prepending a fake token to the text,

2005

so that it uses only the CLI command rules. Then the parser invokes

2006

an execution routine corresponding to the command, which either constructs

2007

the whole reply and returns it back or (in case it expects the reply will be long)

2008

it prints a partial reply and asks the CLI module (using the <B>cont</B> hook)

2009

to call it again when the output is transferred to the user.

2010

<P>The <B>this_cli</B> variable points to a <I>cli</I> structure of the session being

2011

currently parsed, but it's of course available only in command handlers

2012

not entered using the <B>cont</B> hook.

2013

<P>TX buffer management works as follows: At cli.tx_buf there is a

2014

list of TX buffers (struct cli_out), cli.tx_write is the buffer

2015

currently used by the producer (<B>cli_printf()</B>, <B>cli_alloc_out()</B>) and

2016

cli.tx_pos is the buffer currently used by the consumer

2017

(<B>cli_write()</B>, in system dependent code). The producer uses

2018

cli_out.wpos ptr as the current write position and the consumer

2019

uses cli_out.outpos ptr as the current read position. When the

2020

producer produces something, it calls <B>cli_write_trigger()</B>. If there

2021

is not enough space in the current buffer, the producer allocates

2022

the new one. When the consumer processes everything in the buffer

2023

queue, it calls <B>cli_written()</B>, tha frees all buffers (except the

2024

first one) and schedules cli.event .

2025

<P>

2026

<P><HR><H3>Function</H3>

2027

2028

<B>cli_printf</B>

2029

(<I>cli *</I> <B>c</B>, <I>int</I> <B>code</B>, <I>char *</I> <B>msg</B>, <I>...</I> <B>...</B>) -- send reply to a CLI connection

2030

<P>

2031

<H3>Arguments</H3>

2032

<P>

2033

<DL>

2034

<DT><I>cli *</I> <B>c</B><DD><P>CLI connection

2035

<DT><I>int</I> <B>code</B><DD><P>numeric code of the reply, negative for continuation lines

2036

<DT><I>char *</I> <B>msg</B><DD><P>a <B>printf()</B>-like formatting string.

2037

<DT><I>...</I> <B>...</B><DD><P>variable arguments

2038

</DL>

2039

<H3>Description</H3>

2040

<P>This function send a single line of reply to a given CLI connection.

2041

In works in all aspects like <B>bsprintf()</B> except that it automatically

2042

prepends the reply line prefix.

2043

<P>Please note that if the connection can be already busy sending some

2044

data in which case <B>cli_printf()</B> stores the output to a temporary buffer,

2045

so please avoid sending a large batch of replies without waiting

2046

for the buffers to be flushed.

2047

<P>If you want to write to the current CLI output, you can use the <B>cli_msg()</B>

2048

macro instead.

2049

2050

2051

<HR><H3>Function</H3>

2052

2053

2054

(<B>void</B>) -- initialize the CLI module

2055

<P>

2056

<H3>Description</H3>

2057

<P>

2058

<P>This function is called during BIRD startup to initialize

2059

the internal data structures of the CLI module.

2060

2061

<H2><A NAME="ss2.9">2.9</A> <A HREF="prog.html#toc2.9">Object locks</A>

2062

</H2>

2063

2064

<P>

2065

<P>The lock module provides a simple mechanism for avoiding conflicts between

2066

various protocols which would like to use a single physical resource (for

2067

example a network port). It would be easy to say that such collisions can

2068

occur only when the user specifies an invalid configuration and therefore

2069

he deserves to get what he has asked for, but unfortunately they can also

2070

arise legitimately when the daemon is reconfigured and there exists (although

2071

for a short time period only) an old protocol instance being shut down and a new one

2072

willing to start up on the same interface.

2073

<P>The solution is very simple: when any protocol wishes to use a network port

2074

or some other non-shareable resource, it asks the core to lock it and it doesn't

2075

use the resource until it's notified that it has acquired the lock.

2076

<P>Object locks are represented by <I>object_lock</I> structures which are in turn a kind of

2077

resource. Lockable resources are uniquely determined by resource type

2078

(<I>OBJLOCK_UDP</I> for a UDP port etc.), IP address (usually a broadcast or

2079

multicast address the port is bound to), port number and interface.

2080

<P>

2081

<P><HR><H3>Function</H3>

2082

<P><I>struct object_lock *</I>

2083

<B>olock_new</B>

2084

(<I>pool *</I> <B>p</B>) -- create an object lock

2085

<P>

2086

<H3>Arguments</H3>

2087

<P>

2088

<DL>

2089

<DT><I>pool *</I> <B>p</B><DD><P>resource pool to create the lock in.

2090

</DL>

2091

<H3>Description</H3>

2092

<P>The <B>olock_new()</B> function creates a new resource of type <I>object_lock</I>

2093

and returns a pointer to it. After filling in the structure, the caller

2094

should call <B>olock_acquire()</B> to do the real locking.

2095

2096

2097

<HR><H3>Function</H3>

2098

2099

<B>olock_acquire</B>

2100

(<I>struct object_lock *</I> <B>l</B>) -- acquire a lock

2101

<P>

2102

<H3>Arguments</H3>

2103

<P>

2104

<DL>

2105

<DT><I>struct object_lock *</I> <B>l</B><DD><P>the lock to acquire

2106

</DL>

2107

<H3>Description</H3>

2108

<P>This function attempts to acquire exclusive access to the non-shareable

2109

resource described by the lock <B>l</B>. It returns immediately, but as soon

2110

as the resource becomes available, it calls the <B>hook()</B> function set up

2111

by the caller.

2112

<P>When you want to release the resource, just <B>rfree()</B> the lock.

2113

2114

2115

<HR><H3>Function</H3>

2116

2117

<B>olock_init</B>

2118

(<B>void</B>) -- initialize the object lock mechanism

2119

<P>

2120

<H3>Description</H3>

2121

<P>

2122

<P>This function is called during BIRD startup. It initializes

2123

all the internal data structures of the lock module.

2124

2125

<HR>

2126

2127

<A HREF="prog-1.html">Previous</A>

2128

<A HREF="prog.html#toc2">Contents</A>

2129

</BODY>

2130

</HTML>

Older »