#include <unistd.h>
#endif
-/* The k5buf module is intended to allow multi-step string
- construction in a fixed or dynamic buffer without the need to check
- for a failure at each step (and without aborting on malloc
- failure). If an allocation failure occurs or if the fixed buffer
- runs out of room, the error will be discovered when the caller
- retrieves the C string value or checks the length of the resulting
- buffer.
-
- k5buf structures are stack-allocated, but are intended to be
- opaque, so do not access the fields directly. This is a tool, not
- a way of life, so do not put k5buf structure pointers into the
- public API or into significant internal APIs. */
-
-/* We must define the k5buf structure here to allow stack allocation.
- The structure is intended to be opaque, so the fields have funny
- names. */
+/*
+ * The k5buf module is intended to allow multi-step string construction in a
+ * fixed or dynamic buffer without the need to check for a failure at each step
+ * (and without aborting on malloc failure). If an allocation failure occurs
+ * or if the fixed buffer runs out of room, the error will be discovered when
+ * the caller retrieves the C string value or checks the length of the
+ * resulting buffer.
+ *
+ * k5buf structures are stack-allocated, but are intended to be opaque, so do
+ * not access the fields directly. This is a tool, not a way of life, so do
+ * not put k5buf structure pointers into the public API or into significant
+ * internal APIs.
+ */
+
+/*
+ * We must define the k5buf structure here to allow stack allocation. The
+ * structure is intended to be opaque, so the fields have funny names.
+ */
struct k5buf {
int xx_buftype;
char *xx_data;
size_t xx_len;
};
-/** Initialize a k5buf using a fixed-sized, existing buffer. SPACE
- must be more than zero, or an assertion failure will result. */
+/** Initialize a k5buf using a fixed-sized, existing buffer. SPACE must be
+ * more than zero, or an assertion failure will result. */
void krb5int_buf_init_fixed(struct k5buf *buf, char *data, size_t space);
-/** Initialize a k5buf using an internally allocated dynamic buffer.
- The buffer contents must be freed with krb5int_free_buf. */
+/** Initialize a k5buf using an internally allocated dynamic buffer. The
+ * buffer contents must be freed with krb5int_free_buf. */
void krb5int_buf_init_dynamic(struct k5buf *buf);
/** Add a C string to BUF. */
void krb5int_buf_add(struct k5buf *buf, const char *data);
-/** Add a counted set of bytes to BUF. It is okay for DATA[0..LEN-1]
- to contain null bytes if you are prepared to deal with that in the
- output (use krb5int_buf_len to retrieve the length of the output). */
+/**
+ * Add a counted set of bytes to BUF. It is okay for DATA[0..LEN-1]
+ * to contain null bytes if you are prepared to deal with that in the
+ * output (use krb5int_buf_len to retrieve the length of the output).
+ */
void krb5int_buf_add_len(struct k5buf *buf, const char *data, size_t len);
/** Add sprintf-style formatted data to BUF. */
;
/** Truncate BUF. LEN must be between 0 and the existing buffer
- length, or an assertion failure will result. */
+ * length, or an assertion failure will result. */
void krb5int_buf_truncate(struct k5buf *buf, size_t len);
-/** Retrieve the byte array value of BUF, or NULL if there has been an
- allocation failure or the fixed buffer ran out of room.
+/**
+ * Retrieve the byte array value of BUF, or NULL if there has been an
+ * allocation failure or the fixed buffer ran out of room.
- The byte array will be a C string unless binary data was added with
- krb5int_buf_add_len; it will be null-terminated regardless.
- Modifying the byte array does not invalidate the buffer, as long as
- its length is not changed.
+ * The byte array will be a C string unless binary data was added with
+ * krb5int_buf_add_len; it will be null-terminated regardless.
+ * Modifying the byte array does not invalidate the buffer, as long as
+ * its length is not changed.
- For a fixed buffer, the return value will always be equal to the
- passed-in value of DATA at initialization time if it is not NULL.
+ * For a fixed buffer, the return value will always be equal to the
+ * passed-in value of DATA at initialization time if it is not NULL.
- For a dynamic buffer, any buffer modification operation except
- krb5int_buf_truncate may invalidate the byte array address. */
+ * For a dynamic buffer, any buffer modification operation except
+ * krb5int_buf_truncate may invalidate the byte array address.
+ */
char *krb5int_buf_data(struct k5buf *buf);
-/** Retrieve the length of BUF, or -1 if there has been an allocation
- failure or the fixed buffer ran out of room. The length is equal
- to strlen(krb5int_buf_data(buf)) unless binary data was added with
- krb5int_buf_add_len. */
+/**
+ * Retrieve the length of BUF, or -1 if there has been an allocation
+ * failure or the fixed buffer ran out of room. The length is equal
+ * to strlen(krb5int_buf_data(buf)) unless binary data was added with
+ * krb5int_buf_add_len.
+ */
ssize_t krb5int_buf_len(struct k5buf *buf);
-/** Free the storage used in the dynamic buffer BUF. The caller may
- choose to take responsibility for freeing the return value of
- krb5int_buf_data instead of using this function. If BUF is a fixed
- buffer, an assertion failure will result. It is unnecessary
- (though harmless) to free a buffer after an error is detected; the
- storage will already have been freed in that case. */
+/**
+ * Free the storage used in the dynamic buffer BUF. The caller may
+ * choose to take responsibility for freeing the return value of
+ * krb5int_buf_data instead of using this function. If BUF is a fixed
+ * buffer, an assertion failure will result. It is unnecessary
+ * (though harmless) to free a buffer after an error is detected; the
+ * storage will already have been freed in that case.
+ */
void krb5int_free_buf(struct k5buf *buf);
#endif /* K5_BUF_H */
projects / krb5.git / commitdiff