1 files changed, 138 insertions, 0 deletions
diff --git a/static/freebsd/man3/libder_obj.3 b/static/freebsd/man3/libder_obj.3
new file mode 100644
index 00000000..d7e51da1
--- /dev/null
+++ b/static/freebsd/man3/libder_obj.3
@@ -0,0 +1,138 @@
+.\"
+.\" SPDX-Copyright-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (C) 2024 Kyle Evans <kevans@FreeBSD.org>
+.\"
+.Dd March 2, 2024
+.Dt LIBDER_OBJ 3
+.Os
+.Sh NAME
+.Nm libder_obj ,
+.Nm libder_obj_alloc ,
+.Nm libder_obj_alloc_simple ,
+.Nm libder_obj_free ,
+.Nm libder_obj_append ,
+.Nm libder_obj_child ,
+.Nm libder_obj_next ,
+.Nm libder_obj_type ,
+.Nm libder_obj_type_simple ,
+.Nm libder_obj_data ,
+.Nm libder_obj_dump
+.Nd inspecting and creating libder objects
+.Sh LIBRARY
+.Lb libder
+.Sh SYNOPSIS
+.In libder.h
+.Ft struct libder_object *
+.Fn libder_obj_alloc "struct libder_ctx *ctx" "struct libder_tag *type" "const uint8_t *data" "size_t datasz"
+.Ft struct libder_object *
+.Fn libder_obj_alloc_simple "struct libder_ctx *ctx" "uint8_t type" "const uint8_t *data" "size_t datasz"
+.Ft void
+.Fn libder_obj_free "struct libder_object *ctx"
+.Ft bool
+.Fn libder_obj_append "struct libder_object *parent" "struct libder_object *child"
+.Ft struct libder_object *
+.Fn libder_obj_child "const struct libder_object *obj" "size_t which"
+.Ft struct libder_object *
+.Fn libder_obj_next "const struct libder_object *obj"
+.Fn "DER_FOREACH_CHILD" "struct libder_obj *iter" "struct libder_obj *obj"
+.Fn "DER_FOREACH_CHILD_SAFE" "struct libder_obj *iter" "struct libder_obj *obj" "struct libder_obj *tmp"
+.Ft struct libder_tag *
+.Fn libder_obj_type "const struct libder_object *obj"
+.Ft uint8_t
+.Fn libder_obj_type_simple "const struct libder_object *obj"
+.Ft const uint8_t *
+.Fn libder_obj_data "const struct libder_object *obj" "size_t *sz"
+.Ft void
+.Fn libder_obj_dump "const struct libder_object *obj" "FILE *fp"
+.Sh DESCRIPTION
+The
+.Nm
+family of functions may be used by the application to create its own objects and
+object hierarchy, rather than reading them from an existing stream.
+.Pp
+The
+.Fn libder_obj_alloc
+and
+.Fn libder_obj_alloc_simple
+functions allocate a new object with the specified
+.Fa type
+and
+.Fa data .
+Most applications will likely prefer to use the
+.Dq simple
+variant to avoid having to manage a
+.Xr libder_type 3
+lifecycle and associated boilerplate.
+The base variant remains around for when
+.Xr libder_type 3
+grows the necessary API to create arbitrarily large tags.
+.Pp
+The
+.Fn libder_obj_append
+function is used to append
+.Fa obj
+to the
+.Fa parent
+object's children.
+For example, to add an object to a sequence.
+.Pp
+The
+.Fn libder_obj_child
+and
+.Fn libder_obj_next
+functions are used to iterate through the children of
+.Fa obj .
+The
+.Fa which
+argument to
+.Fn libder_obj_child
+specifies the index of the child requested, starting at
+.Dv 0 .
+The
+.Fn DER_FOREACH_CHILD
+and
+.Fn DER_FOREACH_CHILD_SAFE
+macros are provided for convenience.
+The difference between these two is that it is safe to free the iterator in the
+.Fn DER_FOREACH_CHILD_SAFE
+loop body.
+.Pp
+The
+.Fn libder_obj_type
+and
+.Fn libder_obj_type_simple
+functions are used to get the type information about an
+.Fa obj .
+As usual, the
+.Dq simple
+variant will return the one-byte encoding of a tag between 0 and 30.
+If the tag is actually larger than 30, then all of the lower 5 bits will be set
+to indicate that it's a long tag, and that the application should have used
+.Fn libder_obj_type
+instead.
+.Pp
+The
+.Fn libder_obj_data
+function returns a pointer to the
+.Fa data
+from
+.Fa obj ,
+and updates
+.Fa *sz
+with the data's size.
+Note that the data is not copied out here, the application is responsible for
+making its own copy of the returned buffer.
+.Pp
+The
+.Fn libder_obj_dump
+function is a debugging function that likely shouldn't be used.
+A human readable representation of the provided
+.Fa obj
+will be written to the stream
+.Fa fp .
+.Sh SEE ALSO
+.Xr libder 3 ,
+.Xr libder_read 3 ,
+.Xr libder_type 3 ,
+.Xr libder_write 3