Debian Codegraph @

upstream/debian-trixie/man3/asprintf.3

raw
1 '\" t
2 .\" Copyright (C) 2001 Andries Brouwer <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Text fragments inspired by Martin Schulze <[email protected]>.
7 .\"
8 .TH asprintf 3 2024-06-15 "Linux man-pages 6.9.1"
9 .SH NAME
10 asprintf, vasprintf \- print to allocated string
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ", " \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
17 .B #include <stdio.h>
18 .P
19 .BI "int asprintf(char **restrict " strp ", const char *restrict " fmt ", ...);"
20 .BI "int vasprintf(char **restrict " strp ", const char *restrict " fmt ,
21 .BI " va_list " ap );
22 .fi
23 .SH DESCRIPTION
24 The functions
25 .BR asprintf ()
26 and
27 .BR vasprintf ()
28 are analogs of
29 .BR sprintf (3)
30 and
31 .BR vsprintf (3),
32 except that they allocate a string large enough to hold the output
33 including the terminating null byte (\[aq]\[rs]0\[aq]),
34 and return a pointer to it via the first argument.
35 This pointer should be passed to
36 .BR free (3)
37 to release the allocated storage when it is no longer needed.
38 .SH RETURN VALUE
39 When successful, these functions return the number of bytes printed,
40 just like
41 .BR sprintf (3).
42 If memory allocation wasn't possible, or some other error occurs,
43 these functions will return \-1, and the contents of
44 .I strp
45 are undefined.
46 .SH ATTRIBUTES
47 For an explanation of the terms used in this section, see
48 .BR attributes (7).
49 .TS
50 allbox;
51 lbx lb lb
52 l l l.
53 Interface Attribute Value
54 T{
55 .na
56 .nh
57 .BR asprintf (),
58 .BR vasprintf ()
59 T} Thread safety MT-Safe locale
60 .TE
61 .SH VERSIONS
62 The FreeBSD implementation sets
63 .I strp
64 to NULL on error.
65 .SH STANDARDS
66 GNU, BSD.
67 .SH SEE ALSO
68 .BR free (3),
69 .BR malloc (3),
70 .BR printf (3)