<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cutter-Cutter">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Cutter.top_of_page">Cutter</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CUTTER Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Cutter</refname>
<refpurpose>A Unit Testing Framework for C and C++.</refpurpose>
</refnamediv>

<refsect1 id="cutter-Cutter.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="setup">setup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-setup">cut_setup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="teardown">teardown</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-teardown">cut_teardown</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-startup">cut_startup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-shutdown">cut_shutdown</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-add-data">cut_add_data</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="cut-add-data-backward-compatibility">cut_add_data_backward_compatibility</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-set-attributes">cut_set_attributes</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="CutTestContext"><returnvalue>CutTestContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cut-get-current-test-context">cut_get_current_test_context</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-set-current-test-context">cut_set_current_test_context</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-set-message">cut_set_message</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-set-message-va-list">cut_set_message_va_list</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-keep-message">cut_keep_message</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cut-message">cut_message</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="cutter-Cutter.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CUT-EXPORT:CAPS">CUT_EXPORT</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>


<refsect1 id="cutter-Cutter.description" role="desc">
<title role="desc.title">Description</title>
<para>Cutter is a Unit Testing Framework for C and C++ and has
the following features:</para>
<itemizedlist>
  <listitem><para>
Easy to use. Cutter doesn't introduce any magic macros
like CUTTER_DEFINE_TEST_START and CUTTER_DEFINE_TEST_END
into your test program. You can write your test program
like normal program. You only use <link linkend="cut-assert-XXX"><function>cut_assert_XXX()</function></link> to
check that your program works as you expect.
<informalexample><programlisting><![CDATA[
#include <cutter.h>
#include "my-stack.h"

void
test_my_stack (void)
{
    MyStack *stack = my_stack_new();

    cut_assert_not_null(stack);
    cut_assert(my_stack_is_empty(stack));
    cut_assert_equal_int(0, my_stack_get_size(stack));

    my_stack_push(stack, 10);
    cut_assert(!my_stack_is_empty(stack));
    cut_assert_equal_int(1, my_stack_get_size(stack));

    my_stack_push(stack, 20);
    cut_assert_equal_int(2, my_stack_get_size(stack));

    cut_assert_equal(20, my_stack_pop(stack));
    cut_assert(!my_stack_is_empty(stack));
    cut_assert_equal_int(1, my_stack_get_size(stack));

    cut_assert_equal(10, my_stack_pop(stack));
    cut_assert(my_stack_is_empty(stack));
    cut_assert_equal_int(0, my_stack_get_size(stack));
}
]]></programlisting></informalexample>
  </para></listitem>
  <listitem><para>
Simple but useful output. Cutter works quietly if tests
are running without any problems by default. The
following is an output of self test:
<informalexample><programlisting><![CDATA[
...........................................................

Finished in 0.213021 seconds

59 test(s), 246 assertion(s), 0 failure(s), 0 error(s), 0 pending(s), 0 notification(s)
]]></programlisting></informalexample>
Cutter just outputs "." for a passed test and a summary
at the end. Cutter doesn't output each test name, how
many assertions are used for a test and so because we
don't need the information on success.
  </para><para>
Cutter outputs many information on failure:
<informalexample><programlisting><![CDATA[
.....................F.....................................

1) Failure: test_error
<"Strange" == cut_test_result_get_test_name(result)>
expected: <Strange!!!>
 but was: <dummy-error-test>
test/test-cut-assertions.c:240: cut_assert_test_result()

Finished in 0.223657 seconds

59 test(s), 242 assertion(s), 1 failure(s), 0 error(s), 0 pending(s), 0 notification(s)
]]></programlisting></informalexample>
The above result is happened because I add a strange
expected staring in Cutter's self test:
<informalexample><programlisting><![CDATA[
cut_assert_equal_string("Strange!!!", cut_test_result_get_test_name(result));
]]></programlisting></informalexample>
The strange assertion is written in the 240th line in
test/test-cut-assertions.c and the line is in the
<link linkend="cut-assert-test-result"><function>cut_assert_test_result()</function></link> function. The function is called
in test_error test. We expected
cut_test_result_get_test_name(result) should return
"Strange!!!" but got "dummy-error-name". We can get the
above information from Cutter output. This will help your
debug.
  </para><para>
Cutter's output format is pragmatic. ' but was:' is
indented and aligned with the above 'expected:'. This
helps that you find difference between expected value and
actual value by your eyes easily. The problem line is
formated as 'FILENAME:LINE: FUNCTION' to integrate
Emacs. In Emacs's compilation-mode, if the format is
appeared in *compilation* buffer, we can jump to FILENAME
at LINE with next-error command. (C-x `) This helps that you
find the problem line rapidly.
  </para><para>
Cutter supports not only easy test writing but also easy
debugging.
  </para></listitem>
</itemizedlist>

</refsect1>
<refsect1 id="cutter-Cutter.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="setup" role="function" condition="deprecated:1.0.7: Use cut_setup() instead.">
<title>setup&#160;()</title>
<indexterm zone="setup" role="deprecated"><primary>setup</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
setup (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>setup</literal> has been deprecated since version 1.0.7 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-setup"><function>cut_setup()</function></link> instead.</para>
</warning>
<para>If you define <link linkend="setup"><function>setup()</function></link> in your test program, cutter will
call your <link linkend="setup"><function>setup()</function></link> before each your test is run. If you
define <link linkend="cut-setup"><function>cut_setup()</function></link>, <link linkend="setup"><function>setup()</function></link> is ignored.</para>
</refsect2>
<refsect2 id="cut-setup" role="function" condition="since:1.0.6">
<title>cut_setup&#160;()</title>
<indexterm zone="cut-setup" role="1.0.6"><primary>cut_setup</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_setup (<parameter><type>void</type></parameter>);</programlisting>
<para>If you define <link linkend="cut-setup"><function>cut_setup()</function></link> in your test program, cutter
will call your <link linkend="cut-setup"><function>cut_setup()</function></link> before each your test is
run. <link linkend="cut-setup"><function>cut_setup()</function></link> has priority over <link linkend="setup"><function>setup()</function></link>.</para>
<para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="teardown" role="function" condition="deprecated:1.0.7: Use cut_teardown() instead.">
<title>teardown&#160;()</title>
<indexterm zone="teardown" role="deprecated"><primary>teardown</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
teardown (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>teardown</literal> has been deprecated since version 1.0.7 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-teardown"><function>cut_teardown()</function></link> instead.</para>
</warning>
<para>If you define <link linkend="teardown"><function>teardown()</function></link> in your test program, cutter will
call your <link linkend="teardown"><function>teardown()</function></link> after each your test is run even if
a test is failed. If you define <link linkend="cut-teardown"><function>cut_teardown()</function></link>,
<link linkend="teardown"><function>teardown()</function></link> is ignored.</para>
</refsect2>
<refsect2 id="cut-teardown" role="function" condition="since:1.0.6">
<title>cut_teardown&#160;()</title>
<indexterm zone="cut-teardown" role="1.0.6"><primary>cut_teardown</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_teardown (<parameter><type>void</type></parameter>);</programlisting>
<para>If you define <link linkend="cut-teardown"><function>cut_teardown()</function></link> in your test program, cutter
will call your <link linkend="cut-teardown"><function>cut_teardown()</function></link> after each your test is run
even if a test is failed. <link linkend="cut-teardown"><function>cut_teardown()</function></link> has priority
over <link linkend="teardown"><function>teardown()</function></link>.</para>
<para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="cut-startup" role="function" condition="since:1.0.6">
<title>cut_startup&#160;()</title>
<indexterm zone="cut-startup" role="1.0.6"><primary>cut_startup</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_startup (<parameter><type>void</type></parameter>);</programlisting>
<para>If you define <link linkend="cut-startup"><function>cut_startup()</function></link> in your test program, cutter
will call your <link linkend="cut-startup"><function>cut_startup()</function></link> before each your test case
is run. <link linkend="cut-startup"><function>cut_startup()</function></link> has priority over <link linkend="startup"><function>startup()</function></link>.</para>
<para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="cut-shutdown" role="function" condition="since:1.0.6">
<title>cut_shutdown&#160;()</title>
<indexterm zone="cut-shutdown" role="1.0.6"><primary>cut_shutdown</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_shutdown (<parameter><type>void</type></parameter>);</programlisting>
<para>If you define <link linkend="shutdown"><function>shutdown()</function></link> in your test program, cutter
will call your <link linkend="shutdown"><function>shutdown()</function></link> after each your test case is
run.  <link linkend="cut-shutdown"><function>cut_shutdown()</function></link> has priority over <link linkend="shutdown"><function>shutdown()</function></link>.</para>
<para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="cut-add-data" role="macro" condition="since:1.0.3">
<title>cut_add_data()</title>
<indexterm zone="cut-add-data" role="1.0.3"><primary>cut_add_data</primary></indexterm>
<programlisting language="C">#define             cut_add_data(first_data_name, ...)</programlisting>
<para>Adds data to use data driven test.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
#include <cutter.h>

void data_translate (void);
void test_translate (const void *data);

static const char*
translate (int input)
{
   switch(input) {
   case 1:
       return "first";
   case 111:
       return "a hundred eleven";
   default:
       return "unsupported";
   }
}

typedef struct _TranslateTestData
{
    char *translated;
    int input;
} TranslateTestData;

static TranslateTestData *
translate_test_data_new (char *translated, int input)
{
    TranslateTestData *data;

    data = malloc(sizeof(TranslateTestData));
    data->translated = strdup(translated);
    data->input = input;

    return data;
}

static void
translate_test_data_free (TranslateTestData *data)
{
    free(data->translated);
    free(data);
}

void
data_translate(void)
{
    cut_add_data("simple data",
                 translate_test_data_new("first", 1),
                 translate_test_data_free,
                 "complex data",
                 translate_test_data_new("a hundred eleven", 111),
                 translate_test_data_free,
                 NULL);
}

void
test_translate(const void *data)
{
     const TranslateTestData *test_data = data;

     cut_assert_equal_string(test_data->translated,
                             translate(test_data->input));
}
]]></programlisting></informalexample>
<para></para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>first_data_name</para></entry>
<entry role="parameter_description"><para>The first data name.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>The data and destroy function of the first data,
followed optionally by more
name/data/destroy_function(<link linkend="CutDestroyFunction"><type>CutDestroyFunction</type></link>)
triples. The variable arguments should be terminated
by <link linkend="NULL:CAPS"><literal>NULL</literal></link> since 1.0.6.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0.3">1.0.3</link></para></refsect2>
<refsect2 id="cut-add-data-backward-compatibility" role="macro" condition="deprecated:">
<title>cut_add_data_backward_compatibility()</title>
<indexterm zone="cut-add-data-backward-compatibility" role="deprecated"><primary>cut_add_data_backward_compatibility</primary></indexterm>
<programlisting language="C">#define             cut_add_data_backward_compatibility(context, ...)</programlisting>
<warning><para><literal>cut_add_data_backward_compatibility</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
</para>
</refsect2>
<refsect2 id="cut-set-attributes" role="function" condition="since:1.0.4">
<title>cut_set_attributes&#160;()</title>
<indexterm zone="cut-set-attributes" role="1.0.4"><primary>cut_set_attributes</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_set_attributes (<parameter>const <link linkend="char"><type>char</type></link> *first_attribute_name</parameter>,
                    <parameter>...</parameter>);</programlisting>
<para>Sets attributes of the test.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
#include <cutter.h>

void attributes_repeat (void);
void test_repeat (void);

void
attributes_repeat(void)
{
    cut_set_attributes("description", "a test for repeat function",
                       "bug", "111",
                       "priority", "high",
                       NULL);
}

void
test_repeat(void)
{
     cut_assert_equal_string_with_free("XXX", repeat("X", 3));
}
]]></programlisting></informalexample>
<para></para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>first_attribute_name</para></entry>
<entry role="parameter_description"><para>The first attribute name.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>The value of the first attribute, followed
optionally by more name/value pairs.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required since 1.0.7.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0.4">1.0.4</link></para></refsect2>
<refsect2 id="cut-get-current-test-context" role="function" condition="since:1.0.4">
<title>cut_get_current_test_context&#160;()</title>
<indexterm zone="cut-get-current-test-context" role="1.0.4"><primary>cut_get_current_test_context</primary></indexterm>
<programlisting language="C"><link linkend="CutTestContext"><returnvalue>CutTestContext</returnvalue></link>&#160;*
cut_get_current_test_context (<parameter><type>void</type></parameter>);</programlisting>
<para>Returns the current test context. The current test
context is a thread local object. It means that you don't
need to care this if you don't create a new thread in your
test. This is only needed to care if you create a new
thread. You need to pass the current test context in your
test thread to the current test context in a created
thread.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
int
your_thread_function(void *data)
{
    CutTestContext *test_context = data;
    cut_set_current_test_context(test_context);
    ...
}

void
run_your_thread(void)
{
    int result;
    pthread_t your_thread;

    result = pthread_create(&your_thread, NULL,
                            your_thread_function,
                            cut_get_current_test_context());
    ...
}
]]></programlisting></informalexample>
<para></para>
<refsect3 role="returns">
<title>Returns</title>
<para> a <link linkend="CutTestContext"><type>CutTestContext</type></link>.</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.0.4">1.0.4</link></para></refsect2>
<refsect2 id="cut-set-current-test-context" role="function" condition="since:1.0.4">
<title>cut_set_current_test_context&#160;()</title>
<indexterm zone="cut-set-current-test-context" role="1.0.4"><primary>cut_set_current_test_context</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_set_current_test_context (<parameter><link linkend="CutTestContext"><type>CutTestContext</type></link> *test_context</parameter>);</programlisting>
<para>Set <parameter>test_context</parameter>
 as the current test context. See
<link linkend="cut-get-current-test-context"><function>cut_get_current_test_context()</function></link> for more details.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>test_context</para></entry>
<entry role="parameter_description"><para>the <link linkend="CutTestContext"><type>CutTestContext</type></link> to be the current test
context.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0.4">1.0.4</link></para></refsect2>
<refsect2 id="cut-set-message" role="function" condition="deprecated:1.1.0: Use cut_message() instead.|since:1.0.6">
<title>cut_set_message&#160;()</title>
<indexterm zone="cut-set-message" role="deprecated"><primary>cut_set_message</primary></indexterm><indexterm zone="cut-set-message" role="1.0.6"><primary>cut_set_message</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_set_message (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                 <parameter>...</parameter>);</programlisting>
<warning><para><literal>cut_set_message</literal> has been deprecated since version 1.1.0 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-message"><function>cut_message()</function></link> instead.</para>
</warning>
<para>Sets a message to be used by the next assertion.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="cut-set-message-va-list" role="function" condition="deprecated:1.1.0: Use cut_message() instead.|since:1.0.6">
<title>cut_set_message_va_list&#160;()</title>
<indexterm zone="cut-set-message-va-list" role="deprecated"><primary>cut_set_message_va_list</primary></indexterm><indexterm zone="cut-set-message-va-list" role="1.0.6"><primary>cut_set_message_va_list</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_set_message_va_list (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                         <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<warning><para><literal>cut_set_message_va_list</literal> has been deprecated since version 1.1.0 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-message"><function>cut_message()</function></link> instead.</para>
</warning>
<para>Sets a message to be used by the next assertion.</para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="cut-keep-message" role="function" condition="deprecated:1.1.0: Use cut_message() instead.|since:1.0.6">
<title>cut_keep_message&#160;()</title>
<indexterm zone="cut-keep-message" role="deprecated"><primary>cut_keep_message</primary></indexterm><indexterm zone="cut-keep-message" role="1.0.6"><primary>cut_keep_message</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_keep_message (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>cut_keep_message</literal> has been deprecated since version 1.1.0 and should not be used in newly-written code.</para> <para>Use <link linkend="cut-message"><function>cut_message()</function></link> instead.</para>
</warning>
<para>Keeps the current message set by <link linkend="cut-set-message"><function>cut_set_message()</function></link> or
<link linkend="cut-set-message-va-list"><function>cut_set_message_va_list()</function></link> after the next assertion.</para>
<para role="since">Since: <link linkend="api-index-1.0.6">1.0.6</link></para></refsect2>
<refsect2 id="cut-message" role="function" condition="since:1.1.0">
<title>cut_message&#160;()</title>
<indexterm zone="cut-message" role="1.1.0"><primary>cut_message</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cut_message (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
             <parameter>...</parameter>);</programlisting>
<para>Specifies optional assertion message.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
cut_assert_equal_string("abc", "def",
                        cut_message("should fail!"));
]]></programlisting></informalexample>
<para></para>
<refsect3 role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>format</para></entry>
<entry role="parameter_description"><para>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>the parameters to insert into the format string.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.1.0">1.1.0</link></para></refsect2>

</refsect1>
<refsect1 id="cutter-Cutter.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="CUT-EXPORT:CAPS" role="macro" condition="since:1.1.2">
<title>CUT_EXPORT</title>
<indexterm zone="CUT-EXPORT:CAPS" role="1.1.2"><primary>CUT_EXPORT</primary></indexterm>
<programlisting language="C">#  define CUT_EXPORT __declspec(dllexport)
</programlisting>
<para>Marks a function as a exported function. This is needed
for just Windows environment. If you want to run your
tests on Windows, you need to use this. Otherwise, you
don't need to use this.</para>
<para>e.g.:</para>
<informalexample><programlisting><![CDATA[
CUT_EXPORT void
test_add (void)
{
  ...
}
]]></programlisting></informalexample>
<para></para>
<para role="since">Since: <link linkend="api-index-1.1.2">1.1.2</link></para></refsect2>

</refsect1>
<refsect1 id="cutter-Cutter.see-also">
<title>See Also</title>
<link linkend="cutter-Assertions">Assertions</link>

</refsect1>

</refentry>
