Skip to content

API Reference

Jump to bottom
weigao edited this page Jun 21, 2026 · 1 revision

API Reference

This page provides the complete API reference for cfstream.

It is intended as a lookup page for function declarations, parameters, return values, behavior, and important notes.

For tutorial-style documentation, see:

Overview

cfstream provides two public headers:

Header Language Main Purpose
cfs.hpp C++ C++ interface with namespace support and independent C++ file streams
cfs.h C C interface for standard input/output redirection

Current version:

1.3.0

C++ API

The C++ API is provided by:

#include "cfs.hpp"

All C++ APIs are inside the cfs namespace.

namespace cfs {
    static std::ifstream cin;
    static std::ofstream cout;

    static inline const char* getversion();

    static inline void cfs(const char* input, const char* output);
    static inline void closecfs();

    static inline void cppfs(const char* input, const char* output);
    static inline void closecppfs();
}

cfs::getversion()

Declaration

static inline const char* cfs::getversion();

Description

Returns the current cfstream version.

Parameters

None.

Return Value

Type Description
const char* Current cfstream version string

For version 1.3.0, the returned string is:

1.3.0

Behavior

This function does not perform file operations.

Example

#include <iostream>
#include "cfs.hpp"

int main() {
    std::cout << cfs::getversion() << '\n';
    return 0;
}

cfs::cfs()

Declaration

static inline void cfs::cfs(const char* input, const char* output);

Description

Redirects standard input and/or standard output.

This function is similar to using freopen directly, but wrapped by cfstream.

Parameters

Parameter Type Description
input const char* Input file name. If NULL, input is not redirected.
output const char* Output file name. If NULL, output is not redirected.

In C++11 or later, nullptr can also be used instead of NULL.

Return Value

None.

Behavior

Internally, this function uses:

std::freopen(input, "r", stdin);
std::freopen(output, "w", stdout);

when the corresponding parameter is not null.

After successful redirection, the following streams/functions are affected:

std::cin
std::cout
scanf
printf

They will use the redirected standard input/output streams.

Notes

  • Passing NULL or nullptr means the corresponding stream will not be redirected.
  • Passing both parameters as NULL or nullptr is allowed, but has no practical effect.
  • This function does not open cfs::cin or cfs::cout.
  • Use cfs::closecfs() to restore standard streams to the console.

Example

#include <iostream>
#include "cfs.hpp"

int main() {
    cfs::cfs("test.in", "test.out");

    int n;
    std::cin >> n;
    std::cout << n << '\n';

    cfs::closecfs();
    return 0;
}

cfs::closecfs()

Declaration

static inline void cfs::closecfs();

Description

Ends the file redirection created by cfs::cfs() and attempts to restore standard input and output back to the console.

Parameters

None.

Return Value

None.

Behavior

Internally, this function redirects stdin and stdout back to platform-specific console devices.

Platform Console Device
Windows CON
Linux / macOS / other Unix-like systems /dev/tty

Notes

  • This function does not permanently close std::cin or std::cout.
  • It redirects the standard streams back to the console device.
  • It does not affect cfs::cin or cfs::cout.
  • For independent C++ file streams, use cfs::closecppfs() instead.

Example

#include <iostream>
#include "cfs.hpp"

int main() {
    cfs::cfs("test.in", "test.out");

    int n;
    std::cin >> n;
    std::cout << n << '\n';

    cfs::closecfs();

    std::cout << "Back to console" << '\n';
    return 0;
}

cfs::cppfs()

Declaration

static inline void cfs::cppfs(const char* input, const char* output);

Description

Opens independent C++ file streams:

cfs::cin
cfs::cout

These streams are separate from standard streams.

Parameters

Parameter Type Description
input const char* Input file name for cfs::cin
output const char* Output file name for cfs::cout

Return Value

None.

Behavior

If neither cfs::cin nor cfs::cout is open, this function opens:

cfs::cin.open(input);
cfs::cout.open(output);

If either cfs::cin or cfs::cout is already open, this function does not reopen them and prints an error message to std::cerr:

Error-from-cfs Already open cppfs,please close first!

Notes

  • cfs::cppfs() does not redirect std::cin or std::cout.
  • scanf and printf are not affected.
  • Do not pass NULL or nullptr to cfs::cppfs().
  • If you need single-side redirection, use cfs::cfs() instead.
  • Use cfs::closecppfs() before calling cfs::cppfs() again.

Example

#include <iostream>
#include "cfs.hpp"

int main() {
    cfs::cppfs("test.in", "test.out");

    int n;
    cfs::cin >> n;
    cfs::cout << n << '\n';

    std::cout << "This goes to the console." << '\n';

    cfs::closecppfs();
    return 0;
}

cfs::closecppfs()

Declaration

static inline void cfs::closecppfs();

Description

Closes the independent C++ file streams opened by cfs::cppfs().

Parameters

None.

Return Value

None.

Behavior

This function checks whether the streams are open and closes them if needed:

if (cin.is_open()) cin.close();
if (cout.is_open()) cout.close();

Notes

  • This function only affects cfs::cin and cfs::cout.
  • It does not affect std::cin, std::cout, scanf, or printf.
  • After calling cfs::closecppfs(), do not continue using cfs::cin or cfs::cout unless you call cfs::cppfs() again.

Example

#include "cfs.hpp"

int main() {
    cfs::cppfs("test.in", "test.out");

    int n;
    cfs::cin >> n;
    cfs::cout << n << '\n';

    cfs::closecppfs();
    return 0;
}

cfs::cin

Declaration

static std::ifstream cfs::cin;

Description

Input file stream used by cfs::cppfs().

Type

std::ifstream

Behavior

After calling:

cfs::cppfs("test.in", "test.out");

cfs::cin reads from test.in.

Notes

  • cfs::cin is independent from std::cin.
  • It is only opened by cfs::cppfs().
  • It is closed by cfs::closecppfs().
  • It has internal linkage because it is declared with static.

Example

int n;
cfs::cin >> n;

cfs::cout

Declaration

static std::ofstream cfs::cout;

Description

Output file stream used by cfs::cppfs().

Type

std::ofstream

Behavior

After calling:

cfs::cppfs("test.in", "test.out");

cfs::cout writes to test.out.

Notes

  • cfs::cout is independent from std::cout.
  • It is only opened by cfs::cppfs().
  • It is closed by cfs::closecppfs().
  • It has internal linkage because it is declared with static.

Example

cfs::cout << "Hello cfstream" << '\n';

C API

The C API is provided by:

#include "cfs.h"

The C API does not use a namespace.

static inline const char* cfs_getversion(void);

static inline void cfs(const char* input, const char* output);
static inline void closecfs(void);

cfs_getversion()

Declaration

static inline const char* cfs_getversion(void);

Description

Returns the current cfstream version.

Parameters

None.

Return Value

Type Description
const char* Current cfstream version string

For version 1.3.0, the returned string is:

1.3.0

Behavior

This function does not perform file operations.

Example

#include "cfs.h"

int main(void) {
    printf("%s\n", cfs_getversion());
    return 0;
}

cfs()

Declaration

static inline void cfs(const char* input, const char* output);

Description

Redirects standard input and/or standard output.

This function is similar to using freopen directly, but wrapped by cfstream.

Parameters

Parameter Type Description
input const char* Input file name. If NULL, input is not redirected.
output const char* Output file name. If NULL, output is not redirected.

Return Value

None.

Behavior

Internally, this function uses:

freopen(input, "r", stdin);
freopen(output, "w", stdout);

when the corresponding parameter is not NULL.

After successful redirection, the following functions are affected:

scanf
printf

They will use the redirected standard input/output streams.

Notes

  • Passing NULL means the corresponding stream will not be redirected.
  • C does not support nullptr.
  • Passing both parameters as NULL is allowed, but has no practical effect.
  • Use closecfs() to restore standard streams to the console.

Example

#include "cfs.h"

int main(void) {
    cfs("test.in", "test.out");

    int n;
    scanf("%d", &n);
    printf("%d\n", n);

    closecfs();
    return 0;
}

closecfs()

Declaration

static inline void closecfs(void);

Description

Ends the file redirection created by cfs() and attempts to restore standard input and output back to the console.

Parameters

None.

Return Value

None.

Behavior

Internally, this function redirects stdin and stdout back to platform-specific console devices.

Platform Console Device
Windows CON
Linux / macOS / other Unix-like systems /dev/tty

Notes

  • This function does not permanently close stdin or stdout.
  • It redirects the standard streams back to the console device.
  • It should be used after cfs() when you no longer need file redirection.

Example

#include "cfs.h"

int main(void) {
    cfs("test.in", "test.out");

    int n;
    scanf("%d", &n);
    printf("%d\n", n);

    closecfs();

    printf("Back to console\n");
    return 0;
}

Parameter Rules

Interface Parameter NULL Allowed nullptr Allowed Notes
cfs::cfs input Yes C++11 or later If null, input is not redirected
cfs::cfs output Yes C++11 or later If null, output is not redirected
cfs input Yes No C does not support nullptr
cfs output Yes No C does not support nullptr
cfs::cppfs input Not recommended Not recommended Use a valid file name
cfs::cppfs output Not recommended Not recommended Use a valid file name

Return Values

API Return Type Meaning
cfs::getversion() const char* Current cfstream version
cfs_getversion() const char* Current cfstream version
cfs::cfs() void No return value
cfs::closecfs() void No return value
cfs::cppfs() void No return value
cfs::closecppfs() void No return value
cfs() void No return value
closecfs() void No return value

Error Behavior

cfs::cppfs() already open

If cfs::cppfs() is called while cfs::cin or cfs::cout is already open, it prints this message to std::cerr:

Error-from-cfs Already open cppfs,please close first!

The function then returns without reopening the streams.

C standard too old

If cfs.h is compiled as C with a standard lower than C99, compilation stops with:

cfs.h requires C99 or later.

Platform Behavior

closecfs() and cfs::closecfs() use platform-specific console devices to restore standard streams.

Platform stdin Restore Target stdout Restore Target
Windows CON CON
Linux / macOS / other Unix-like systems /dev/tty /dev/tty

Linkage Notes

C++ header

In cfs.hpp, cfs::cin and cfs::cout are declared with static.

This gives them internal linkage.

Each translation unit that includes cfs.hpp gets its own private copy of:

cfs::cin
cfs::cout

C header

In cfs.h, the functions are defined as static inline.

This allows the header to be included in multiple C source files without external linker conflicts.

When cfs.h is included from C++ code, the C interface is wrapped with extern "C".

See Also

cfstream Wiki

English

中文

Back to Repository

Clone this wiki locally