blob: f658048a9369a666725dea12fa7057b5ee37fcbe (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
.\" $OpenBSD: BUF_MEM_new.3,v 1.5 2016/11/10 14:34:18 jmc Exp $
.\"
.Dd $Mdocdate: November 10 2016 $
.Dt BUF_MEM_NEW 3
.Os
.Sh NAME
.Nm BUF_MEM_new ,
.Nm BUF_MEM_free ,
.Nm BUF_MEM_grow ,
.Nm BUF_strdup
.Nd simple character arrays structure
.Sh SYNOPSIS
.In openssl/buffer.h
.Ft BUF_MEM *
.Fo BUF_MEM_new
.Fa void
.Fc
.Ft void
.Fo BUF_MEM_free
.Fa "BUF_MEM *a"
.Fc
.Ft int
.Fo BUF_MEM_grow
.Fa "BUF_MEM *str"
.Fa "size_t len"
.Fc
.Ft char *
.Fo BUF_strdup
.Fa "const char *str"
.Fc
.Sh DESCRIPTION
The buffer library handles simple character arrays.
Buffers are used for various purposes in the library, most notably
memory BIOs.
.Pp
The library uses the
.Vt BUF_MEM
structure defined in buffer.h:
.Bd -literal
typedef struct buf_mem_st
{
size_t length; /* current number of bytes */
char *data;
size_t max; /* size of buffer */
} BUF_MEM;
.Ed
.Pp
.Fa length
is the current size of the buffer in bytes;
.Fa max
is the amount of memory allocated to the buffer.
There are three functions which handle these and one miscellaneous function.
.Pp
.Fn BUF_MEM_new
allocates a new buffer of zero size.
.Pp
.Fn BUF_MEM_free
frees up an already existing buffer.
The data is zeroed before freeing up in case the buffer contains
sensitive data.
.Pp
.Fn BUF_MEM_grow
changes the size of an already existing buffer to
.Fa len .
Any data already in the buffer is preserved if it increases in size.
.Pp
.Fn BUF_strdup
copies a NUL terminated string into a block of allocated memory and
returns a pointer to the allocated block.
Unlike the system
.Xr strdup 3
function,
.Fn BUF_strdup
will accept a
.Dv NULL
argument and will return
.Dv NULL
in that case.
Its use in new programs is discouraged.
.Pp
The memory allocated from
.Fn BUF_strdup
should be freed up using the
.Xr free 3
function.
.Sh RETURN VALUES
.Fn BUF_MEM_new
returns the buffer or
.Dv NULL
on error.
.Pp
.Fn BUF_MEM_grow
returns zero on error or the new size (i.e.\&
.Fa len ) .
.Sh SEE ALSO
.Xr bio 3
.Sh HISTORY
.Fn BUF_MEM_new ,
.Fn BUF_MEM_free
and
.Fn BUF_MEM_grow
are available in all versions of SSLeay and OpenSSL.
.Fn BUF_strdup
was added in SSLeay 0.8.
|
