man3/cfree.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH CFREE 3 2007-07-26  "" "Linux Programmer's Manual"
  25 .SH NAME
  26 cfree \- free allocated memory
  27 .SH SYNOPSIS
  28 .nf
  29 .sp
  30 .B "#include <stdlib.h>"
  31 .sp
  32 /* In SunOS 4 */
  33 .BI "int cfree(void *" ptr );
  34 .sp
  35 /* In glibc or FreeBSD libcompat */
  36 .BI "void cfree(void *" ptr );
  37 .sp
  38 /* In SCO OpenServer */
  39 .BI "void cfree(char *" ptr ", unsigned " num ", unsigned " size );
  40 .sp
  41 /* In Solaris watchmalloc.so.1 */
  42 .BI "void cfree(void *" ptr ", size_t " nelem ", size_t " elsize );
  43 .fi
  44 .sp
  45 .in -4n
  46 Feature Test Macro Requirements for glibc (see
  47 .BR feature_test_macros (7)):
  48 .in
  49 .sp
  50 .BR cfree ():
  51 _BSD_SOURCE || _SVID_SOURCE
  52 .SH DESCRIPTION
  53 This function should never be used.
  54 Use
  55 .BR free (3)
  56 instead.
  57 .SS 1-arg cfree
  58 In glibc, the function
  59 .BR cfree ()
  60 is a synonym for
  61 .BR free (3),
  62 "added for compatibility with SunOS".
  63 .LP
  64 Other systems have other functions with this name.
  65 The declaration is sometimes in
  66 .I <stdlib.h>
  67 and sometimes in
  68 .IR <malloc.h> .
  69 .SS 3-arg cfree
  70 Some SCO and Solaris versions have malloc libraries with a 3-argument
  71 .BR cfree (),
  72 apparently as an analog to
  73 .BR calloc (3).
  74 .LP
  75 If you need it while porting something, add
  76 .sp
  77 .in +4n
  78 #define cfree(p, n, s) free((p))
  79 .in
  80 .sp
  81 to your file.
  82 .LP
  83 A frequently asked question is "Can I use
  84 .BR free (3)
  85 to free memory allocated with
  86 .BR calloc (3),
  87 or do I need
  88 .BR cfree ()?"
  89 Answer: use
  90 .BR free (3).
  91 .LP
  92 An SCO manual writes: "The cfree routine is provided for compliance
  93 to the iBCSe2 standard and simply calls free.
  94 The num and size
  95 arguments to cfree are not used."
  96 .SH RETURN VALUE
  97 The SunOS version of
  98 .BR cfree ()
  99 (which is a synonym for
 100 .BR free (3))
 101 returns 1 on success and 0 on failure.
 102 In case of error,
 103 .I errno
 104 is set to
 105 .BR EINVAL :
 106 the value of
 107 .I ptr
 108 was not a pointer to a block previously allocated by
 109 one of the routines in the
 110 .BR malloc (3)
 111 family.
 112 .SH CONFORMING TO
 113 The 3-argument version of
 114 .BR cfree ()
 115 as used by SCO conforms to the iBCSe2 standard:
 116 Intel386 Binary Compatibility Specification, Edition 2.
 117 .SH SEE ALSO
 118 .BR malloc (3)