stdio.h File Reference

Contains those _s-functions that are related to stdio. More...

#include <stdarg.h>
#include "./base_.h"
#include "./stddef.h"
#include "./errno.h"

Go to the source code of this file.

Defines
#define	L_tmpnam_s   25
	Specifies the array size required for storing temporary filenames generated by tmpnam_s.
#define	TMP_MAX_S   TMP_MAX
	maximum amount of unique filenames, which function tmpnam_s can generate
Functions
errno_t	tmpfile_s (FILE *restrict *restrict streamptr)
	This function creates a temporary file.
errno_t	tmpnam_s (char *s, rsize_t maxsize)
	This function creates a file or directory name that is unique for the specified temporary directory.
char *	gets_s (char *s, rsize_t n)
	The gets_s function reads one line from stdin into s.
errno_t	fopen_s (FILE *restrict *restrict streamptr, const char *restrict filename, const char *restrict mode)
	The fopen_s function opens the file specified by filename.
errno_t	freopen_s (FILE *restrict *restrict newstreamptr, const char *restrict filename, const char *restrict mode, FILE *restrict stream)
	The freopen_s function opens filename and closes stream.
int	sprintf_s (char *restrict s, rsize_t n, const char *restrict format,...) __attribute__((format(printf
	This function allows fomatted output into buffer s while taking into account its size.
int int	snprintf_s (char *restrict s, rsize_t n, const char *restrict format,...) __attribute__((format(printf
	This function allows fomatted output into buffer s while taking into account its size.
int int int	vsprintf_s (char *restrict s, rsize_t n, const char *restrict format, va_list arg) __attribute__((format(printf
	The vsprintf_s function is equivalent to sprintf_s but expects a va_list argument.
int int int int	vsnprintf_s (char *restrict s, rsize_t n, const char *restrict format, va_list arg) __attribute__((format(printf
	The vsnprintf_s function is equivalent to snprintf_s but expects a va_list argument.
int int int int int	fprintf_s (FILE *restrict stream, const char *restrict format,...)
	The fprintf_s function is analogous to the fprintf function except that the n specifier is not allowed.
int	vfprintf_s (FILE *restrict stream, const char *restrict format, va_list arg)
	The vfprintf_s function is equivalent to fprintf_s but expects a va_list argument.
int	printf_s (const char *restrict format,...)
	The printf_s function behaves as fprintf_s when fprintf_s is called with an argument of stdout.
int	vprintf_s (const char *restrict format, va_list arg)
	The vprintf_s function is equivalent to printf_s but expects a va_list argument.
int	scanf_s (const char *restrict format,...)
	The scanf_s function behaves as fscanf_s when fscanf_s is called with an argument of stdin.
int	vscanf_s (const char *restrict format, va_list arg)
	The vscanf_s function is equivalent to scanf_s but expects a va_list argument.
int	vsscanf_s (const char *restrict s, const char *restrict format, va_list arg)
	The vsscanf_s function is equivalent to sscanf_s but expects a va_list argument.
int	sscanf_s (const char *restrict s, const char *restrict format,...)
	The sscanf_s function is analogous to fscanf_s but reads from a string instead of a stream.
int	fscanf_s (FILE *restrict stream, const char *restrict format,...)
	A secure variant of fscanf that expects the caller to specify the size for each buffer argument.
int	vfscanf_s (FILE *restrict stream, const char *restrict format, va_list arg)
	vfscanf_s is equivalent to fscanf_s but expects a va_list argument.

---

Detailed Description

Contains those _s-functions that are related to stdio.

---

Function Documentation

errno_t fopen_s	(	FILE *restrict *restrict	streamptr,
		const char *restrict	filename,
		const char *restrict	mode
	)

The fopen_s function opens the file specified by filename.

Runtime-constraints:

A runtime-constraint violation occurs

• streamptr is a null pointer
• filename is a null pointer
• MODE is a null pointer

Parameters:

[out]	streamptr	On success it is set to the opened FILE * stream.
[in]	filename	the name of the file to be opened
[in]	mode	determines how the file should be opend. It supports the same flags as fopen with some additions.

Returns:

Zero if the file was successfully opened. Non-zero if it could not open the file or a runtime-constraint violation occurred.

See also:

fopen

int int int int int fprintf_s	(	FILE *restrict	stream,
		const char *restrict	format,
			...
	)

The fprintf_s function is analogous to the fprintf function except that the n specifier is not allowed.

Parameters:

[in]	stream	the output stream
[in]	format	printf-style format flags (n disallowed)
[in]	...	a variable number of arguments corresponding to the given format flags

Returns:

the number of characters written a negative value in case of an output error or runtime constraint violation

See also:

fprintf

errno_t freopen_s	(	FILE *restrict *restrict	newstreamptr,
		const char *restrict	filename,
		const char *restrict	mode,
		FILE *restrict	stream
	)

The freopen_s function opens filename and closes stream.

Runtime-constraints:

A runtime-constraint violation occurs

• newstreamptr is a null pointer
• stream is a null pointer
• mode is a null pointer

Parameters:

[out]	newstreamptr	contains the result of opening filename
[in]	filename	the name of the file to be opened
[in]	mode	determines how the file should be opened. same meaning as for fopen_s
[in]	stream	the stream to be closed

Returns:

Zero if the file was successfully opened. Non-zero if it could not open the file or a runtime-constraint violation occurred.

See also:

freopen

int fscanf_s	(	FILE *restrict	stream,
		const char *restrict	format,
			...
	)

A secure variant of fscanf that expects the caller to specify the size for each buffer argument.

The fscanf_s function is equivalent to fscanf but handles the c, s, and [ conversion specifiers differently. These conversion specifiers now expect a pair of arguments: the first one is a pointer to a buffer (as before) while the second one is expected to be of type rsize_t and specifies the size of the buffer.

Parameters:

[in]	stream
[in]	format
[out]	...	a variable number of arguments corresponding to the given format string

Returns:

EOF if there was a runtime-constraint violation or an input failure occurred before any conversion. Otherwise the number of successfully assigned input items is returned.

See also:

fscanf

char* gets_s	(	char *	s,
		rsize_t	n
	)

The gets_s function reads one line from stdin into s.

Unlike the traditional gets function a second parameter n that specifies the size of s is expected. It is considered a runtime-constraint violation if no newline, EOF or read error occurrs within reading n-1 bytes.

Parameters:

[out]	s	the target buffer
[in]	n	the size of s

Returns:

The gets_s function returns s if successful. NULL is returned if there was a runtime-constraint violation or if end-of-file is encountered and no caracters have been read into the array or if a read error occured.

See also:

gets

int printf_s	(	const char *restrict	format,
			...
	)

The printf_s function behaves as fprintf_s when fprintf_s is called with an argument of stdout.

Parameters:

[in]	format	printf-style format flags (n disallowed)
[in]	...	a variable number of arguments corresponding to the given format flags

Returns:

the number of characters written a negative value in case of an output error or runtime constraint violation

See also:

fprintf_s

int scanf_s	(	const char *restrict	format,
			...
	)

The scanf_s function behaves as fscanf_s when fscanf_s is called with an argument of stdin.

Parameters:

[in]	format	scanf-style format string
[out]	...	a variable number of arguments corresponding to the given format string

Returns:

EOF if there was a runtime-constraint violation or an input failure occurred before any conversion. Otherwise the number of successfully assigned input items is returned.

See also:

fscanf_s

int int snprintf_s	(	char *restrict	s,
		rsize_t	n,
		const char *restrict	format,
			...
	)

This function allows fomatted output into buffer s while taking into account its size.

A maximum of n-1 characters are written into the buffer s, followed by a zero byte.

The snprintf_s function is equivalent to the sprintf function except the following. The n specifier (modified or not by flags, field width, or precision) shall not appear in the string pointed to by format.

The snprintf_s function, unlike sprintf_s, will truncate the result to fit within the array pointed to by s.

The output is made only without truncation, if the return value is positive (> 0) and the returned value <n.

Parameters:

[out]	s	destination buffer containing the output
[in]	n	size of buffer s
[in]	format	format-string (equal to printf)
[in]	...	a variable number of arguments corresponding to the given format flags

Returns:

the number of characters that would have been written (not counting the null byte) had the buffer been sufficiently large a negative number in case of a runtime-constraint violation Thus, the output has been completely written if and only if a positive value that is less than n is returned.

int sprintf_s	(	char *restrict	s,
		rsize_t	n,
		const char *restrict	format,
			...
	)

This function allows fomatted output into buffer s while taking into account its size.

A maximum of n-1 characters are written into the buffer s, followed by a zero byte.

The sprintf_s function is equivalent to the sprintf function except the following. The n specifier (modified or not by flags, field width, or precision) shall not appear in the string pointed to by format.

The sprintf_s function, unlike snprintf_s, treats a result too big for the array pointed to by s as a runtime-constraint violation.

Parameters:

[out]	s	destination buffer containing the output
[in]	n	size of buffer s
[in]	format	format string (equal to printf)
[in]	...	a variable number of arguments corresponding to the given format string

Returns:

the number of characters written (not counting the null byte) a negative number in case of an encoding error 0 in case of runtime-constraint violation

int sscanf_s	(	const char *restrict	s,
		const char *restrict	format,
			...
	)

The sscanf_s function is analogous to fscanf_s but reads from a string instead of a stream.

Parameters:

[in]	s	the string to be parsed
[in]	format	scanf-style format string
[out]	...	a variable number of arguments corresponding to the given format string

Returns:

EOF if there was a runtime-constraint violation or an input failure occurred before any conversion. Otherwise the number of successfully assigned input items is returned.

See also:

fscanf_s

errno_t tmpfile_s

(

FILE *restrict *restrict

streamptr

)

This function creates a temporary file.

The temporary file is guaranteed to be different from any other existing file. The file is opend in binary read/write (w+b) mode. When the file is closed or the program teminates the file is removed automatically.

Remarks:

In contrast to tmpfile, tmpfile_s returns a file with exclusive access and 600 permissions.

By default, the file is created in /tmp. However, it is possible to change this directory by calling slibc_set_tmp_dir.

Runtime-constraints:

A runtime-constraint violation occurs if

• streamptr is a NULL pointer

Parameters:

[out]

streamptr

pointer to the temporary file created

Returns:

0 if the file was created successfully. A non-zero value is returned if the file could not be created or there was a runtime-constraint violation.

See also:

tmpfile

errno_t tmpnam_s	(	char *	s,
		rsize_t	maxsize
	)

This function creates a file or directory name that is unique for the specified temporary directory.

The generated file or directory name is guaranteed to be different from any other existing name in the temporary directory. The default temporary directory is /tmp but can be changed via slibc_set_tmp_dir. The output buffer needs to be at least of length L_tmpnam_s if the default directory location of /tmp is used. In case the slibc temporary directory is changed to a longer directory name by calling slibc_set_tmp_dir the output buffer is required to be of size L_tmpnam_s + strlen(set_tmp_dir). Otherwise calling tmpnam_s might fail. (It will never overflow the buffer though). The function is potentially capable of generating TMP_MAX_S different strings.

Remarks:

Use of this function is normally discouraged because this function does not create the file. It shares this isse wit the traditional tmpnam function. In more detail, a race condition between calling this function and the time of the actual file/directory creation exists. It is, thus, possible that an attacker creates a file with same name in the meantime. Thus, the ISO standard recommends using tmpfile_s where possible. One possible reasonable use of this function is when the user wants to create a temporary directory name. The use of this function is secure in the author's opinion when you have set the temporary directory to a non-shared directory where only your user is allowed to write.

Parameters:

s	[out] On success s will contain the generated unique temporary file name.
maxsize	[in] The size of s.

Returns:

Zero on success. A non-zero value is returned in case of a runtime-constraint violation or if no suitable string can be generated.

See also:

tmpnam

int vfprintf_s	(	FILE *restrict	stream,
		const char *restrict	format,
		va_list	arg
	)

The vfprintf_s function is equivalent to fprintf_s but expects a va_list argument.

Parameters:

[in]	stream	the output stream
[in]	format	printf-style format flags (n disallowed)
[in]	arg	va_list initialized by va_start

Returns:

the number of characters written a negative value in case of an output error or runtime constraint violation

See also:

fprintf_s

int vfscanf_s	(	FILE *restrict	stream,
		const char *restrict	format,
		va_list	arg
	)

vfscanf_s is equivalent to fscanf_s but expects a va_list argument.

Parameters:

[in]	stream	the input stream
[in]	format	the format string
[out]	arg	contains the variable argument list initialized by the va_start macro

Returns:

EOF if there was a runtime-constraint violation or an input failure occurred before any conversion. Otherwise the number of successfully assigned input items is returned.

See also:

fscanf_s

int vprintf_s	(	const char *restrict	format,
		va_list	arg
	)

The vprintf_s function is equivalent to printf_s but expects a va_list argument.

Parameters:

[in]	format	printf-style format string
[in]	arg

Returns:

the number of characters written a negative value in case of an output error or runtime constraint violation

See also:

printf_s

int vscanf_s	(	const char *restrict	format,
		va_list	arg
	)

The vscanf_s function is equivalent to scanf_s but expects a va_list argument.

Parameters:

[in]	format
[out]	arg

Returns:

EOF if there was a runtime-constraint violation or an input failure occurred before any conversion. Otherwise the number of successfully assigned input items is returned.

See also:

scanf_s

int int int int vsnprintf_s	(	char *restrict	s,
		rsize_t	n,
		const char *restrict	format,
		va_list	arg
	)

The vsnprintf_s function is equivalent to snprintf_s but expects a va_list argument.

Parameters:

[out]	s	destination buffer containing the output
[in]	n	size of buffer s
[in]	format	format-string (equal to printf)
[in]	arg	a variable number of arguments corresponding to the given format flags

Returns:

the number of characters that would have been written (not counting the null byte) had the buffer been sufficiently large a negative number in case of a runtime-constraint violation Thus, the output has been completely written if and only if a positive value that is less than n is returned.

See also:

snprintf_s

Referenced by snprintf_s().

int int int vsprintf_s	(	char *restrict	s,
		rsize_t	n,
		const char *restrict	format,
		va_list	arg
	)

The vsprintf_s function is equivalent to sprintf_s but expects a va_list argument.

Parameters:

[out]	s	destination buffer containing the output
[in]	n	size of buffer s
[in]	format	format-string (equal to printf)
[in]	arg	list of variable arguments.

Returns:

the number of characters written (not counting the null byte) a negative number in case of an encoding error 0 in case of runtime-constraint violation

See also:

sprintf_s

Referenced by sprintf_s().

int vsscanf_s	(	const char *restrict	s,
		const char *restrict	format,
		va_list	arg
	)

The vsscanf_s function is equivalent to sscanf_s but expects a va_list argument.

Parameters:

[in]	s	the string to be parsed
[in]	format	scanf-style format string
[out]	arg	va_list argument

Returns:

EOF if there was a runtime-constraint violation or an input failure occurred before any conversion. Otherwise the number of successfully assigned input items is returned.

See also:

sscanf_s