=head1 NAME

nbdkit_strdup_intern, nbdkit_strndup_intern, nbdkit_printf_intern,
nbdkit_vprintf_intern - create a string with limited lifetime for nbdkit

=head1 SYNOPSIS

 #include <nbdkit-plugin.h>

 const char *nbdkit_strdup_intern (const char *str);
 const char *nbdkit_strndup_intern (const char *str, size_t n);
 const char *nbdkit_printf_intern (const char *fmt, ...);
 const char *nbdkit_vprintf_intern (const char *fmt, va_list ap);

=head1 DESCRIPTION

Some callbacks are specified to return C<const char *>, even when a
plugin may not have a suitable compile-time constant to return.
Returning dynamically-allocated memory for such a callback would
induce a memory leak or otherwise complicate the plugin to perform
additional bookkeeping.  For these cases, nbdkit provides several
convenience functions for creating a copy of a string for better
lifetime management.

=head2 nbdkit_strdup_intern

=head2 nbdkit_strndup_intern

Returns a copy of C<str>, possibly limited to a maximum of C<n> bytes.
After calling this, the plugin may free C<str> and use this copy in
its place.

If the copy is created outside the scope of a connection (such as
during C<.load> or C<.config>), the lifetime of the copy will last at
least through C<.unload>.

If the copy is created after a client has triggered a connection (such
as during C<.preconnect> or C<.open>), the lifetime will last at least
through C<.close>, but the copy is not safe to share with other
connections.

=head2 C<nbdkit_printf_intern>

=head2 C<nbdkit_vprintf_intern>

Return a string created from a format template, with a lifetime longer
than the current connection.  These are shorthand for passing C<fmt>
to L<asprintf(3)> on a temporary string, then passing that result to
C<nbdkit_strdup_intern>.

=head1 RETURN VALUE

These functions return a string.  This returned string I<must not> be
freed by the caller.  It will be freed by nbdkit.

If there is an error they call L<nbdkit_error(3)> and return C<-1>.

=head1 HISTORY

The intern functions were added in nbdkit 1.24.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<nbdkit-filter(3)>.

=head1 AUTHORS

Eric Blake

=head1 COPYRIGHT

Copyright Red Hat
