1 files changed, 90 insertions, 0 deletions

diff --git a/doc/grecs_asprintf.3 b/doc/grecs_asprintf.3
new file mode 100644
index 0000000..73be7f0
--- /dev/null
+++ b/doc/grecs_asprintf.3
@@ -0,0 +1,90 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 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/>.
+.\" This file is part of SLB. 
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.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:
+