Blame lib/lwres/man/lwres_buffer.html

Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018-2020 Internet Systems Consortium, Inc. ("ISC")
Packit Service ae04f2
 - 
Packit Service ae04f2
 - This Source Code Form is subject to the terms of the Mozilla Public
Packit Service ae04f2
 - License, v. 2.0. If a copy of the MPL was not distributed with this
Packit Service ae04f2
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
Packit Service ae04f2
-->
Packit Service ae04f2
<html lang="en">
Packit Service ae04f2
<head>
Packit Service ae04f2
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
Packit Service ae04f2
<title>lwres_buffer</title>
Packit Service ae04f2
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Packit Service ae04f2
</head>
Packit Service ae04f2
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2
  
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2

Name

Packit Service ae04f2

Packit Service ae04f2
    lwres_buffer_init, 
Packit Service ae04f2
    lwres_buffer_invalidate, 
Packit Service ae04f2
    lwres_buffer_add, 
Packit Service ae04f2
    lwres_buffer_subtract, 
Packit Service ae04f2
    lwres_buffer_clear, 
Packit Service ae04f2
    lwres_buffer_first, 
Packit Service ae04f2
    lwres_buffer_forward, 
Packit Service ae04f2
    lwres_buffer_back, 
Packit Service ae04f2
    lwres_buffer_getuint8, 
Packit Service ae04f2
    lwres_buffer_putuint8, 
Packit Service ae04f2
    lwres_buffer_getuint16, 
Packit Service ae04f2
    lwres_buffer_putuint16, 
Packit Service ae04f2
    lwres_buffer_getuint32, 
Packit Service ae04f2
    lwres_buffer_putuint32, 
Packit Service ae04f2
    lwres_buffer_putmem, 
Packit Service ae04f2
    lwres_buffer_getmem
Packit Service ae04f2
     — lightweight resolver buffer management
Packit Service ae04f2
  

Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2

Synopsis

Packit Service ae04f2
Packit Service ae04f2
    
Packit Service ae04f2
Packit Service ae04f2
#include <lwres/lwbuffer.h>
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_init(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
void *base, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int length);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_invalidate(
Packit Service ae04f2
lwres_buffer_t *b);
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_add(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int n);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_subtract(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int n);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_clear(
Packit Service ae04f2
lwres_buffer_t *b);
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_first(
Packit Service ae04f2
lwres_buffer_t *b);
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_forward(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int n);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_back(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int n);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
uint8_t
Packit Service ae04f2
lwres_buffer_getuint8(
Packit Service ae04f2
lwres_buffer_t *b);
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_putuint8(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
uint8_t val);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
uint16_t
Packit Service ae04f2
lwres_buffer_getuint16(
Packit Service ae04f2
lwres_buffer_t *b);
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_putuint16(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
uint16_t val);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
uint32_t
Packit Service ae04f2
lwres_buffer_getuint32(
Packit Service ae04f2
lwres_buffer_t *b);
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_putuint32(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
uint32_t val);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_putmem(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
const unsigned char *base, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int length);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
void
Packit Service ae04f2
lwres_buffer_getmem(
Packit Service ae04f2
lwres_buffer_t *b, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned char *base, 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
unsigned int length);
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
 
Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2
Packit Service ae04f2
  
Packit Service ae04f2

DESCRIPTION

Packit Service ae04f2
Packit Service ae04f2
Packit Service ae04f2
    

Packit Service ae04f2
      These functions provide bounds checked access to a region of memory
Packit Service ae04f2
      where data is being read or written.
Packit Service ae04f2
      They are based on, and similar to, the
Packit Service ae04f2
      isc_buffer_
Packit Service ae04f2
      functions in the ISC library.
Packit Service ae04f2
    

Packit Service ae04f2
    

Packit Service ae04f2
      A buffer is a region of memory, together with a set of related
Packit Service ae04f2
      subregions.
Packit Service ae04f2
      The used region and the
Packit Service ae04f2
      available region are disjoint, and
Packit Service ae04f2
      their union is the buffer's region.
Packit Service ae04f2
      The used region extends from the beginning of the buffer region to the
Packit Service ae04f2
      last used byte.
Packit Service ae04f2
      The available region extends from one byte greater than the last used
Packit Service ae04f2
      byte to the end of the  buffer's region.
Packit Service ae04f2
      The size of the used region can be changed using various
Packit Service ae04f2
      buffer commands.
Packit Service ae04f2
      Initially, the used region is empty.
Packit Service ae04f2
    

Packit Service ae04f2
    

Packit Service ae04f2
      The used region is further subdivided into two disjoint regions: the
Packit Service ae04f2
      consumed region and the remaining region.
Packit Service ae04f2
      The union of these two regions is the used region.
Packit Service ae04f2
      The consumed region extends from the beginning of the used region to
Packit Service ae04f2
      the byte before the current offset (if any).
Packit Service ae04f2
      The remaining region the current pointer to the end
Packit Service ae04f2
      of the used
Packit Service ae04f2
      region.
Packit Service ae04f2
      The size of the consumed region can be changed using various
Packit Service ae04f2
      buffer commands.
Packit Service ae04f2
      Initially, the consumed region is empty.
Packit Service ae04f2
    

Packit Service ae04f2
    

Packit Service ae04f2
      The active region is an (optional) subregion of the
Packit Service ae04f2
      remaining
Packit Service ae04f2
      region.
Packit Service ae04f2
      It extends from the current offset to an offset in the
Packit Service ae04f2
      remaining region.
Packit Service ae04f2
      Initially, the active region is empty.
Packit Service ae04f2
      If the current offset advances beyond the chosen offset,
Packit Service ae04f2
      the active region will also be empty.
Packit Service ae04f2
    

Packit Service ae04f2
    
Packit Service ae04f2
   /------------entire length---------------\\
Packit Service ae04f2
   /----- used region -----\\/-- available --\\
Packit Service ae04f2
   +----------------------------------------+
Packit Service ae04f2
   | consumed  | remaining |                |
Packit Service ae04f2
   +----------------------------------------+
Packit Service ae04f2
   a           b     c     d                e
Packit Service ae04f2
      
Packit Service ae04f2

Packit Service ae04f2
    

Packit Service ae04f2
    
Packit Service ae04f2
  a == base of buffer.
Packit Service ae04f2
  b == current pointer.  Can be anywhere between a and d.
Packit Service ae04f2
  c == active pointer.  Meaningful between b and d.
Packit Service ae04f2
  d == used pointer.
Packit Service ae04f2
  e == length of buffer.
Packit Service ae04f2
      
Packit Service ae04f2

Packit Service ae04f2
    

Packit Service ae04f2
    
Packit Service ae04f2
  a-e == entire length of buffer.
Packit Service ae04f2
  a-d == used region.
Packit Service ae04f2
  a-b == consumed region.
Packit Service ae04f2
  b-d == remaining region.
Packit Service ae04f2
  b-c == optional active region.
Packit Service ae04f2
Packit Service ae04f2

Packit Service ae04f2
    

Packit Service ae04f2
    

lwres_buffer_init()

Packit Service ae04f2
      initializes the
Packit Service ae04f2
      lwres_buffer_t
Packit Service ae04f2
      *b
Packit Service ae04f2
      and associates it with the memory region of size
Packit Service ae04f2
      length
Packit Service ae04f2
      bytes starting at location
Packit Service ae04f2
      base.
Packit Service ae04f2
    

Packit Service ae04f2
    

lwres_buffer_invalidate()

Packit Service ae04f2
      marks the buffer *b
Packit Service ae04f2
      as invalid.  Invalidating a buffer after use is not required,
Packit Service ae04f2
      but makes it possible to catch its possible accidental use.
Packit Service ae04f2
    

Packit Service ae04f2
    

Packit Service ae04f2
      The functions
Packit Service ae04f2
      lwres_buffer_add()
Packit Service ae04f2
      and
Packit Service ae04f2
      lwres_buffer_subtract()
Packit Service ae04f2
      respectively increase and decrease the used space in
Packit Service ae04f2
      buffer
Packit Service ae04f2
      *b
Packit Service ae04f2
      by
Packit Service ae04f2
      n
Packit Service ae04f2
      bytes.
Packit Service ae04f2
      lwres_buffer_add()
Packit Service ae04f2
      checks for buffer overflow and
Packit Service ae04f2
      lwres_buffer_subtract()
Packit Service ae04f2
      checks for underflow.
Packit Service ae04f2
      These functions do not allocate or deallocate memory.
Packit Service ae04f2
      They just change the value of
Packit Service ae04f2
      used.
Packit Service ae04f2
    

Packit Service ae04f2
    

Packit Service ae04f2
      A buffer is re-initialised by
Packit Service ae04f2
      lwres_buffer_clear().
Packit Service ae04f2
      The function sets
Packit Service ae04f2
      used,
Packit Service ae04f2
      current
Packit Service ae04f2
      and
Packit Service ae04f2
      active
Packit Service ae04f2
      to zero.
Packit Service ae04f2
    

Packit Service ae04f2
    

lwres_buffer_first

Packit Service ae04f2
      makes the consumed region of buffer
Packit Service ae04f2
      *p
Packit Service ae04f2
      empty by setting
Packit Service ae04f2
      current
Packit Service ae04f2
      to zero (the start of the buffer).
Packit Service ae04f2
    

Packit Service ae04f2
    

lwres_buffer_forward()

Packit Service ae04f2
      increases the consumed region of buffer
Packit Service ae04f2
      *b
Packit Service ae04f2
      by
Packit Service ae04f2
      n
Packit Service ae04f2
      bytes, checking for overflow.
Packit Service ae04f2
      Similarly,
Packit Service ae04f2
      lwres_buffer_back()
Packit Service ae04f2
      decreases buffer
Packit Service ae04f2
      b's
Packit Service ae04f2
      consumed region by
Packit Service ae04f2
      n
Packit Service ae04f2
      bytes and checks for underflow.
Packit Service ae04f2
    

Packit Service ae04f2
    

lwres_buffer_getuint8()

Packit Service ae04f2
      reads an unsigned 8-bit integer from
Packit Service ae04f2
      *b
Packit Service ae04f2
      and returns it.
Packit Service ae04f2
      lwres_buffer_putuint8()
Packit Service ae04f2
      writes the unsigned 8-bit integer
Packit Service ae04f2
      val
Packit Service ae04f2
      to buffer
Packit Service ae04f2
      *b.
Packit Service ae04f2
    

Packit Service ae04f2
    

lwres_buffer_getuint16()

Packit Service ae04f2
      and
Packit Service ae04f2
      lwres_buffer_getuint32()
Packit Service ae04f2
      are identical to
Packit Service ae04f2
      lwres_buffer_putuint8()
Packit Service ae04f2
      except that they respectively read an unsigned 16-bit or 32-bit integer
Packit Service ae04f2
      in network byte order from
Packit Service ae04f2
      b.
Packit Service ae04f2
      Similarly,
Packit Service ae04f2
      lwres_buffer_putuint16()
Packit Service ae04f2
      and
Packit Service ae04f2
      lwres_buffer_putuint32()
Packit Service ae04f2
      writes the unsigned 16-bit or 32-bit integer
Packit Service ae04f2
      val
Packit Service ae04f2
      to buffer
Packit Service ae04f2
      b,
Packit Service ae04f2
      in network byte order.
Packit Service ae04f2
    

Packit Service ae04f2
    

Packit Service ae04f2
      Arbitrary amounts of data are read or written from a lightweight
Packit Service ae04f2
      resolver buffer with
Packit Service ae04f2
      lwres_buffer_getmem()
Packit Service ae04f2
      and
Packit Service ae04f2
      lwres_buffer_putmem()
Packit Service ae04f2
      respectively.
Packit Service ae04f2
      lwres_buffer_putmem()
Packit Service ae04f2
      copies
Packit Service ae04f2
      length
Packit Service ae04f2
      bytes of memory at
Packit Service ae04f2
      base
Packit Service ae04f2
      to
Packit Service ae04f2
      b.
Packit Service ae04f2
      Conversely,
Packit Service ae04f2
      lwres_buffer_getmem()
Packit Service ae04f2
      copies
Packit Service ae04f2
      length
Packit Service ae04f2
      bytes of memory from
Packit Service ae04f2
      b
Packit Service ae04f2
      to
Packit Service ae04f2
      base.
Packit Service ae04f2
    

Packit Service ae04f2
  
Packit Service ae04f2
</body>
Packit Service ae04f2
</html>