1.Dd May 15, 2001
2.Dt sf_mem 3
3.Os
4.Sh NAME
5.Nm sf_malloc ,
6.Nm sf_calloc ,
7.Nm sf_realloc ,
8.Nm sf_strdup ,
9.Nm strndup ,
10.Nm strfunc_ctl
11.Nd string duplication and safe memory allocation.
12.Pp
13.Sh SYNOPSIS
14.Fd #include <strfunc.h>
15.Pp
16Safe
17.Xr malloc 3
18analog:
19.Ft void *
20.Fn sf_malloc "size_t size"
21.Pp
22Safe
23.Xr calloc 3
24analog:
25.Ft void *
26.Fn sf_calloc "size_t number" "size_t size"
27.Pp
28Safe
29.Xr realloc 3
30analog:
31.Ft void *
32.Fn sf_realloc "void *ptr" "size_t size"
33.Pp
34Duplicate a specified number of characters from the string:
35.Ft char *
36.Fn strndup "const char *a" "size_t num"
37.Pp
38Safe
39.Xr strdup 3
40analog:
41.Ft char *
42.Fn sf_strdup "const char *a"
43.Pp
44.Ft int
45.Fn strfunc_ctl "int request" "int *optArg"
46.Pp
47.Sh DESCRIPTION
48Those functions are used internally by virtually all
49.Nm libstrfunc
50functions to manipulate memory. They are wrappers around the native
51library calls
52.Xr malloc 3 ,
53.Xr calloc 3 ,
54.Xr realloc 3
55and provide additional flexibility in those cases when system is low in memory.
56.Pp
57.Fn strndup
58used to copy the specified number of characters to a newly-created buffer.
59.Pp
60.Fn sf_strdup ,
61.Fn sf_malloc
62and
63.Fn sf_realloc
64are used instead of
65.Xr strdup 3 ,
66.Xr malloc 3
67and
68.Xr realloc 3
69analogs to achieve more control and safety when computer becomes low in memory.
70.Pp
71All functions are defaulted to call
72.Xr abort 3
73upon the unsatisfied memory request. This default behavior can be easily
74changed by using
75.Fn strfunc_ctl
76call with SF_SET_MEMORY_FAILURE_BEHAVIOR.
77.Pp
78.Ft int
79.Fn strfunc_ctl "int request" "int *optArg"
80used to change default behaviour of the previously described functions in
81cases of resource shortage.
82.Pp
83The
84.Em request
85argument can be the following constant:
86.Bd -literal
87	SF_GET_MEMORY_FAILURE_BEHAVIOR
88	SF_SET_MEMORY_FAILURE_BEHAVIOR
89	SF_GET_MEMORY_FAILURE_TRIES
90	SF_SET_MEMORY_FAILURE_TRIES
91.Ed
92.Pp
93to get or set the memory allocation behaviour appropriately.
94While the third and fourth values are used to get or specify the number
95of tries of allocating resources before falling into a failure case,
96the first two values can be used to switch the default behaviour to
97call
98.Xr abort 3
99in case of failure.
100.Em SF_GET_MEMORY_FAILURE_BEHAVIOR
101returns with and
102.Em SF_SET_MEMORY_FAILURE_BEHAVIOR
103accept the following values:
104.Bd -literal
105	SF_ARG_MFB_ABORT      /* call abort(3) on failure, the default */
106	SF_ARG_MFB_ENOMEM     /* return NULL with errno set to ENOMEM */
107	SF_ARG_MFB_TRY_ABORT  /* try N times before calling abort(3) */
108	SF_ARG_MFB_TRY_ENOMEM /* do the same before returning an error */
109	SF_ARG_MFB_TRY_NOFAIL /* loop indefinitely */
110.Ed
111.Pp
112Again, virually all functions defined in
113.Nm libstrfunc
114are aware of this memory control technique, so, for example, you may respect
115that some strfunc library function will not return NULL when you've earlier
116executed something like
117.Bd -literal
118  int memory_control_type = SF_ARG_MFB_TRY_NOFAIL;
119  strfunc_ctl(SF_SET_MEMORY_FAILURE_BEHAVIOR, &memory_control_type);
120.Ed
121.Pp
122.Sh SEE ALSO
123.Xr strfunc 3 ,
124.Xr malloc 3 .
125.Sh AUTHORS
126.An Lev Walkin <vlm@lionet.info>
127