.\" This file is part of grecs -*- nroff -*-
.\" Copyright (C) 2007-2016 Sergey Poznyakoff
.\"
.\" Grecs is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Grecs 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 General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Grecs.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH GRECS_ASPRINTF 3 "May 4, 2011" "GRECS" "Grecs User Reference"
.SH NAME
grecs_asprintf, grecs_vasprintf \- print to allocated string
.SH SYNOPSIS
.nf
.B #include <grecs.h>
.sp
.BI "int grecs_vasprintf(char " "**pbuf" ", size_t " "*psize" \
 ", const char " "*format" ", "
.ti +17
.BI "va_list " "ap" );
.br
.BI "int grecs_asprintf(char " "**pbuf" ", size_t " "*psize" \
 ", const char *" "format" ", ...);"
.SH DESCRIPTION
The functions
.BI grecs_asprintf ()
and
.BI grecs_vasprintf ()
are analogs of
.BR sprintf (3)
and
.BR vsprintf (3),
except that they operate on dynamically allocated buffers.
.PP
If, on entry to the function, \fB*pbuf\fR is NULL and \fB*psize\fR is
0, both functions will allocate a buffer large enough to hold the
formatted message and will fill it with the formatted text.
.PP
If \fB*pbuf\fR is not NULL, \fBpsize\fR must point to its actual size.
If that size is not large enough to accomodate the formatted message,
the buffer will be reallocated accordingly, otherwise it will remain
unchanged.
.PP
In both cases, if the buffer has been reallocated, on return
\fBpbuf\fR will contain its new address and \fBpsize\fR its new size.
.PP
For initial allocation,
.BR grecs_malloc (3)
is used.  To reallocate memory, both functions use
.BR grecs_realloc (3).
.SH RETURN VALUE
None.  If memory allocation fails, a diagnostics is output and the
program is terminated.
.SH "SEE ALSO"
.BR grecs_malloc (3),
.BR grecs_realloc (3).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray+grecs@gnu.org.ua>.
.SH COLOPHON
The \fBGrecs\fR library is constantly changing, so this manual page
may be incorrect or out-of-date.  For the latest copy of \fBGrecs\fR
documentation, visit <http://www.gnu.org.ua/software/grecs>.
.SH COPYRIGHT
Copyright \(co 2011 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: