[v2,09/23] Add <parse_buffer.h>

  This is tailored towards nscd client code parsing needs.  Concurrent
modification is not supported because the nscd clients need to be
changed to make a copy of the data before parsing it (following
the software TM snapshot protocol).

Place the implementation into include/ because it might be useful
beyond the nscd client (say for parsing DNS packets).
---
 include/parse_buffer.h | 213 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 213 insertions(+)
 create mode 100644 include/parse_buffer.h
  

On 3/20/26 4:42 PM, Florian Weimer wrote:
> This is tailored towards nscd client code parsing needs.  Concurrent
> modification is not supported because the nscd clients need to be
> changed to make a copy of the data before parsing it (following
> the software TM snapshot protocol).
> 
> Place the implementation into include/ because it might be useful
> beyond the nscd client (say for parsing DNS packets).

LGTM.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

> ---
>   include/parse_buffer.h | 213 +++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 213 insertions(+)
>   create mode 100644 include/parse_buffer.h
> 
> diff --git a/include/parse_buffer.h b/include/parse_buffer.h
> new file mode 100644
> index 0000000000..b45e40af6d
> --- /dev/null
> +++ b/include/parse_buffer.h
> @@ -0,0 +1,213 @@
> +/* Binary parsing of a fixed-size buffer.
> +   Copyright (C) 2026 Free Software Foundation, Inc.
> +   This file is part of the GNU C Library.
> +
> +   The GNU C Library is free software; you can redistribute it and/or
> +   modify it under the terms of the GNU Lesser General Public
> +   License as published by the Free Software Foundation; either
> +   version 2.1 of the License, or (at your option) any later version.
> +
> +   The GNU C Library is distributed in the hope that it will be useful,
> +   but WITHOUT ANY WARRANTY; without even the implied warranty of
> +   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +   Lesser General Public License for more details.
> +
> +   You should have received a copy of the GNU Lesser General Public
> +   License along with the GNU C Library; if not, see
> +   <https://www.gnu.org/licenses/>.  */
> +
> +#ifndef PARSE_BUFFER_H
> +#define PARSE_BUFFER_H
> +
> +/* Helper functions for parsing binary buffers.
> +
> +   The helpers perform buffer bounds checking on all accesses.  If an
> +   out-of-bounds access is detected, zero or NULL is returned, and the
> +   parse buffer is marked as failed.  Accessed do not need to be
> +   aligned.  All data uses native endianness.  Concurrent modification
> +   of the buffer is not necessarily supported.  */
> +
> +#include <stdbool.h>
> +#include <stddef.h>
> +#include <stdint.h>
> +#include <string.h>
> +
> +struct parse_buffer
> +{
> +  const void *start;
> +  size_t length;
> +};
> +
> +/* Create a parse buffer for LENGTH bytes at START.  If LENGTH is zero,
> +   the new parse buffer is immediately marked as failed.  */
> +static inline struct parse_buffer
> +parse_buffer_create (const void *start, size_t length)
> +{
> +  return (struct parse_buffer) { start, length };
> +}
> +
> +/* Mark *PB as failed.  After that, parse_buffer_has_failed will
> +   return true.  */
> +static inline void
> +parse_buffer_mark_failed (struct parse_buffer *pb)
> +{
> +  pb->length = 0;
> +}
> +
> +/* Return true if *PB has been marked as failed.  */
> +static inline bool
> +parse_buffer_has_failed (const struct parse_buffer *pb)
> +{
> +  return pb->length == 0;
> +}
> +
> +/* Internal function for checking that NEEDED bytes are available in
> +   *PB at OFFSET.  Return false on failure and fail *PB.  A zero value
> +   for NEEDED is considered failure.  */
> +static inline bool
> +__parse_buffer_check_size (struct parse_buffer *pb,
> +                           size_t offset, size_t needed)
> +{
> +  size_t last_byte;
> +  if (needed == 0
> +      || __builtin_add_overflow (offset, needed - 1, &last_byte)
> +      || last_byte >= pb->length)
> +    {
> +      parse_buffer_mark_failed (pb);
> +      return false;
> +    }
> +  return true;
> +}
> +
> +/* Extract an unsigned 8-bit value at OFFSET.  If *PB contains only
> +   OFFSET or fewer bytes, fail *PB and return 0.  */
> +static inline uint8_t
> +parse_buffer_u8 (struct parse_buffer *pb, size_t offset)
> +{
> +  if (offset >= pb->length)
> +    {
> +      parse_buffer_mark_failed (pb);
> +      return 0;
> +    }
> +  return ((uint8_t *) pb->start)[offset];
> +}
> +
> +/* Extract an unsigned 16-bit value at OFFSET.  If 2 bytes are not
> +   available, fail *PB and return 0.  */
> +static inline uint16_t
> +parse_buffer_u16 (struct parse_buffer *pb, size_t offset)
> +{
> +  uint16_t result = 0;
> +  if (__parse_buffer_check_size (pb, offset, sizeof (result)))
> +    memcpy (&result, (uint8_t *) pb->start + offset, sizeof (result));
> +  return result;
> +}
> +
> +/* Extract an unsigned 32-bit value at OFFSET.  If 4 bytes are not
> +   available, fail *PB and return 0.  */
> +static inline uint32_t
> +parse_buffer_u32 (struct parse_buffer *pb, size_t offset)
> +{
> +  uint32_t result = 0;
> +  if (__parse_buffer_check_size (pb, offset, sizeof (result)))
> +    memcpy (&result, (uint8_t *) pb->start + offset, sizeof (result));
> +  return result;
> +}
> +
> +/* Extract an unsigned 64-bit value at OFFSET.  If 8 bytes are not
> +   available, fail *PB and return 0.  */
> +static inline uint64_t
> +parse_buffer_u64 (struct parse_buffer *pb, size_t offset)
> +{
> +  uint64_t result = 0;
> +  if (__parse_buffer_check_size (pb, offset, sizeof (result)))
> +    memcpy (&result, (uint8_t *) pb->start + offset, sizeof (result));
> +  return result;
> +}
> +
> +/* Extract a signed 32-bit value at OFFSET.  If 4 bytes are not
> +   available, fail *PB and return 0.  */
> +static inline int32_t
> +parse_buffer_s32 (struct parse_buffer *pb, size_t offset)
> +{
> +  /* Rely on GCC extension for converting to signed.  */
> +  return parse_buffer_u32 (pb, offset);
> +}
> +
> +/* Extract a signed 64-bit value at OFFSET.  If 8 bytes are not
> +   available, fail *PB and return 0.  */
> +static inline int64_t
> +parse_buffer_s64 (struct parse_buffer *pb, size_t offset)
> +{
> +  /* Rely on GCC extension for converting to signed.  */
> +  return parse_buffer_u64 (pb, offset);
> +}
> +
> +/* Extract an unsigned 32-bit value at *OFFSET and increment *OFFSET
> +   by 4.  If 4 bytes are not available, fail *PB and return 0.  */
> +static inline uint32_t
> +parse_buffer_u32_advance (struct parse_buffer *pb, size_t *offset)
> +{
> +  uint32_t result = 0;
> +  if (__parse_buffer_check_size (pb, *offset, sizeof (result)))
> +    {
> +      memcpy (&result, (uint8_t *) pb->start + *offset, sizeof (result));
> +      *offset += sizeof (result);
> +    }
> +  return result;
> +}
> +
> +/* Return A + B.  On overflow, return 0 and mark *PB as failed.  */
> +static inline size_t
> +parse_buffer_add (struct parse_buffer *pb, size_t a, size_t b)
> +{
> +  size_t result;
> +  if (__builtin_add_overflow (a, b, &result))
> +    {
> +      parse_buffer_mark_failed (pb);
> +      return 0;
> +    }
> +  return result;
> +}
> +
> +/* Extract field MEMBER of the struct type STYP from *PB and return
> +   its value.  The struct starts at OFFSET.  Fail *PB and return zero
> +   if the struct field is not available in *PB (the full struct does
> +   not need to be available).  */
> +#define parse_buffer_field(pb, offset, styp, member)                    \
> +  (_Generic ((styp) { }.member,                                         \
> +             uint8_t: parse_buffer_u8,                                  \
> +             uint16_t: parse_buffer_u16,                                \
> +             uint32_t: parse_buffer_u32,                                \
> +             uint64_t: parse_buffer_u64,                                \
> +             int32_t: parse_buffer_s32,                                 \
> +             int64_t: parse_buffer_s64)                                 \
> +   (pb, parse_buffer_add (pb, offset, offsetof (styp, member))))
> +
> +/* Extract a null-terminated string from a field of size REGION_LENGTH
> +   bytes at *OFFSET in *PB.  If REGION_LENGTH bytes are not available
> +   or the region does not contain a null byte, fail *PB and return
> +   NULL.  *OFFSET is incremented by REGION_LENGTH on success (not just
> +   the size of the string).
> +
> +   Note: The return type should be const char *, but NSS structures
> +   use char * for strings.  To avoid excessive casts, the return type
> +   used here is char *.  */
> +static inline char *
> +parse_buffer_sized_cstring_advance (struct parse_buffer *pb, size_t *offset,
> +                                    size_t region_length)
> +{
> +  if (!__parse_buffer_check_size (pb, *offset, region_length))
> +    return NULL;
> +  const char *result_start = (const char *) pb->start + *offset;
> +  size_t result_length = __strnlen (result_start, region_length);
> +  if (result_length == region_length)
> +    {
> +      parse_buffer_mark_failed (pb);
> +      return NULL;
> +    }
> +  *offset += region_length;
> +  return (char *) result_start;
> +}
> +
> +#endif /* PARSE_BUFFER_H */