Namespaces
Variants

vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
(C99) (C11) (C11) (C11) (C11)
vwprintf vfwprintf vswprintf vwprintf_s vfwprintf_s vswprintf_s vsnwprintf_s
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
헤더 파일에 정의됨 <wchar.h>
(1)
int vwprintf ( const wchar_t * format, va_list vlist ) ;
(C95부터)
(C99까지)
int vwprintf ( const wchar_t * restrict format, va_list vlist ) ;
(C99부터)
(2)
int vfwprintf ( FILE * stream, const wchar_t * format, va_list vlist ) ;
(C95부터)
(C99까지)
int vfwprintf ( FILE * restrict stream,
const wchar_t * restrict format, va_list vlist ) ;
(C99부터)
(3)
int vswprintf ( wchar_t * buffer, size_t bufsz,
const wchar_t * format, va_list vlist ) ;
(C95부터)
(C99까지)
int vswprintf ( wchar_t * restrict buffer, size_t bufsz,
const wchar_t * restrict format, va_list vlist ) ;
(C99부터)
int vwprintf_s ( const wchar_t * restrict format, va_list vlist ) ;
(4) (C11부터)
int vfwprintf_s ( FILE * restrict stream,
const wchar_t * restrict format, va_list vlist ) ;
(5) (C11부터)
int vswprintf_s ( wchar_t * restrict buffer, rsize_t bufsz,
const wchar_t * restrict format, va_list vlist ) ;
(6) (C11부터)
int vsnwprintf_s ( wchar_t * restrict buffer, rsize_t bufsz,
const wchar_t * restrict format, va_list vlist ) ;
(7) (C11부터)

vlist 에 정의된 위치에서 데이터를 로드하고, 이를 와이드 문자열로 변환한 후 다양한 싱크에 결과를 기록합니다.

1) 결과를 stdout 에 기록합니다.
2) 결과를 파일 스트림 stream 에 기록합니다.
3) 결과를 와이드 문자열 buffer 에 기록합니다. 최대 bufsz - 1 개의 와이드 문자와 그 뒤에 널 와이드 문자가 기록됩니다. 결과 와이드 문자열은 bufsz 가 0이 아닌 경우 널 와이드 문자로 종료됩니다.
4-6) (1-3) 와 동일하지만, 다음 오류들은 런타임에 감지되어 현재 설치된 constraint handler 함수를 호출합니다:
  • 변환 지정자 %n 이 format 에 존재하는 경우
  • %s 에 해당하는 인자 중 null pointer가 있는 경우
  • format 또는 buffer 가 null pointer인 경우
  • bufsz 가 0이거나 RSIZE_MAX / sizeof ( wchar_t ) 보다 큰 경우
  • 문자열 및 문자 변환 지정자에서 인코딩 오류가 발생하는 경우
  • ( vswprintf_s 에만 해당) buffer 에 저장될 문자열(종료 널 문자 포함)이 bufsz 를 초과하는 경우
7) (6) 과 동일하지만, 결과를 buffer 가 가리키는 배열 내에 맞도록 잘라냅니다.
모든 경계 검사 함수와 마찬가지로, vwprintf_s , vfwprintf_s , vswprintf_s , 및 vsnwprintf_s 는 구현체가 __STDC_LIB_EXT1__ 를 정의하고, 사용자가 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 으로 정의한 후 <stdio.h> 를 포함할 때만 사용 가능함이 보장됩니다.

목차

매개변수

stream - 출력할 와이드 스트림
buffer - 기록할 와이드 문자열에 대한 포인터
bufsz - 기록할 최대 와이드 문자 수
format - 데이터 해석 방법을 지정하는 널 종료 와이드 문자열에 대한 포인터
vlist - variable argument list 출력할 데이터를 포함하는 가변 인수 목록.


format 문자열은 출력 스트림에 변경 없이 복사되는 일반 와이드 문자( % 제외)와 변환 지정자로 구성됩니다. 각 변환 지정자는 다음 형식을 가집니다:

  • 서론적인 % 문자입니다.
  • (선택적) 변환 동작을 수정하는 하나 이상의 플래그:
  • - : 변환 결과가 필드 내에서 왼쪽 정렬됩니다 (기본값은 오른쪽 정렬).
  • + : 부호 있는 변환의 경우 결과 앞에 항상 부호가 붙습니다 (기본적으로는 결과가 음수일 때만 마이너스 부호가 붙음).
  • space : 부호 있는 변환 결과가 부호 문자로 시작하지 않거나 비어 있는 경우, 결과 앞에 공백이 추가됩니다. + 플래그가 있을 경우 무시됩니다.
  • # : 변환의 대체 형태 가 수행됩니다. 정확한 효과는 아래 표를 참조하십시오. 그렇지 않으면 동작이 정의되지 않습니다.
  • 0 : 정수 및 부동 소수점 숫자 변환의 경우, space 문자 대신 선행 영(0)이 필드를 채우는 데 사용됩니다. 정수 숫자의 경우 정밀도가 명시적으로 지정되면 무시됩니다. 다른 변환에서 이 플래그를 사용하면 동작이 정의되지 않습니다. - 플래그가 있을 경우 무시됩니다.
  • (선택 사항) 정수 값 또는 * 으로 최소 필드 너비를 지정합니다. 결과는 필요한 경우 오른쪽 정렬 시 왼쪽에, 왼쪽 정렬 시 오른쪽에 공백 문자(기본값)로 채워집니다. * 이 사용되는 경우, 너비는 int 타입의 추가 인수로 지정되며, 이 인수는 변환할 인수와 정밀도를 제공하는 인수(있는 경우) 앞에 나타납니다. 인수 값이 음수인 경우 - 플래그가 지정되고 양의 필드 너비로 처리됩니다 (참고: 이는 최소 너비이며 값은 절대 잘리지 않습니다.).
  • (선택적) . 뒤에 정수 숫자나 * , 또는 아무것도 오지 않을 수 있으며, 이것은 변환의 정밀도(precision) 를 지정합니다. * 가 사용되는 경우, 정밀도(precision) 는 int 타입의 추가 인수로 지정되며, 이 인수는 변환될 인수 앞에 나타나지만, 최소 필드 너비를 공급하는 인수가 제공된 경우 그 뒤에 옵니다. 이 인수의 값이 음수이면 무시됩니다. 숫자나 * 가 사용되지 않으면 정밀도는 0으로 취급됩니다. 정밀도(precision) 의 정확한 효과는 아래 표를 참조하십시오.
  • (선택적) 길이 수정자 는 인수의 크기를 지정합니다 (변환 형식 지정자와 결합하여 해당 인수의 유형을 지정합니다).
  • 변환 형식 지정자.

다음 형식 지정자를 사용할 수 있습니다:

변환
지정자 		설명 기대되는
인수 타입
길이 수정자→ hh h 없음 l ll j z t L
C99부터만 사용 가능→ 예 예 예 예 예
% 리터럴 % 를 출력합니다. 전체 변환 지정자는 %% 이어야 합니다. N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

단일 문자 를 기록합니다.

  • 인수는 먼저 wchar_t 로 변환됩니다. 마치 btowc 를 호출하는 것처럼.
  • l 수식어가 사용되면, wint_t 인수가 먼저 wchar_t 로 변환됩니다.
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

문자열 을 기록합니다.

  • 인자는 초기 변환 상태에서 시작하는 멀티바이트 문자 시퀀스를 포함하는 문자 배열의 첫 번째 요소에 대한 포인터여야 하며, 이는 0으로 초기화된 변환 상태로 mbrtowc 호출을 통해 와이드 문자 배열로 변환됩니다.
  • 정밀도 는 기록할 최대 와이드 문자 수를 지정합니다. 정밀도 가 지정되지 않은 경우, 첫 번째 널 종결자까지의 모든 와이드 문자를 기록합니다.
  • l 지정자가 사용된 경우, 인자는 wchar_t 배열의 첫 번째 요소에 대한 포인터여야 합니다.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

부호 있는 정수 를 10진수 표현 [-]dddd 로 변환합니다.

  • 정밀도 는 표시될 최소 자릿수를 지정합니다. 기본 정밀도는 1 입니다.
  • 변환된 값과 정밀도가 모두 ​ 0 ​ 인 경우, 변환 결과로 문자가 생성되지 않습니다.
  • z 수식자의 경우, 예상 인수 타입은 size_t 의 부호 있는 버전입니다.
signed char
short
int
long
long long
※
N/A
o

부호 없는 정수 를 8진수 표현 oooo 로 변환합니다.

  • 정밀도 는 표시될 최소 자릿수를 지정합니다. 기본 정밀도는 1 입니다.
  • 변환된 값과 정밀도가 모두 ​ 0 ​ 인 경우 변환 결과로 아무 문자도 생성되지 않습니다.
  • 대체 구현 에서는 선행 0 하나를 쓰기 위해 필요한 경우 정밀도가 증가됩니다. 이 경우 변환된 값과 정밀도가 모두 ​ 0 ​ 이면 단일 ​ 0 ​ 이 기록됩니다.
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
ptrdiff_t 의 부호 없는 버전
해당 없음
x
X

부호 없는 정수 를 16진수 표현 hhhh 로 변환합니다.

  • x 변환의 경우 abcdef 문자가 사용됩니다.
  • X 변환의 경우 ABCDEF 문자가 사용됩니다.
  • 정밀도 는 표시될 최소 자릿수를 지정합니다. 기본 정밀도는 1 입니다.
  • 변환된 값과 정밀도가 모두 ​ 0 ​ 인 경우 변환 결과로 문자가 생성되지 않습니다.
  • 대체 구현 에서 변환된 값이 0이 아닌 경우 결과 앞에 0x 또는 0X 접두사가 추가됩니다.
N/A
u

부호 없는 정수 를 십진법 표현 dddd 로 변환합니다.

  • 정밀도 는 표시될 최소 자릿수를 지정합니다.
  • 기본 정밀도는 1 입니다.
  • 변환된 값과 정밀도가 모두 ​ 0 ​ 인 경우, 변환 결과로 문자가 생성되지 않습니다.
N/A
f
F (C99)

부동 소수점 숫자 를 [-]ddd.ddd 스타일의 10진수 표기법으로 변환합니다.

  • 정밀도 는 소수점 문자 뒤에 나타날 정확한 자릿수를 지정합니다.
  • 기본 정밀도는 6 입니다.
  • 대체 구현 에서는 숫자가 뒤따르지 않더라도 소수점 문자가 기록됩니다.
  • 무한대 및 NaN(숫자가 아님) 변환 스타일에 대해서는 참고 사항 을 참조하십시오.
N/A N/A
double
double (C99)
N/A N/A N/A N/A
long double
e
E

부동 소수점 숫자 를 10진 지수 표기법으로 변환합니다.

  • e 변환 스타일의 경우 [-]d.ddd  e ±dd 형식이 사용됩니다.
  • E 변환 스타일의 경우 [-]d.ddd  E ±dd 형식이 사용됩니다.
  • 지수는 최소 두 자리 숫자를 포함하며, 필요한 경우에만 더 많은 숫자가 사용됩니다.
  • 값이 ​ 0 ​ 인 경우, 지수도 ​ 0 ​ 입니다.
  • 정밀도 는 소수점 문자 뒤에 나타날 정확한 자릿수를 지정합니다.
  • 기본 정밀도는 6 입니다.
  • 대체 구현 에서는 소수점 문자 뒤에 숫자가 없더라도 소수점 문자가 기록됩니다.
  • 무한대 및 NaN(Not-a-Number) 변환 스타일에 대해서는 참고 사항 을 참조하십시오.
N/A N/A N/A N/A N/A N/A
a
A

(C99)

부동 소수점 숫자 를 16진수 지수 표기법으로 변환합니다.

  • a 변환 스타일의 경우 [-]  0x h.hhh  p ±d 형식을 사용합니다.
  • A 변환 스타일의 경우 [-]  0X h.hhh  P ±d 형식을 사용합니다.
  • 인수가 정규화된 부동 소수점 값인 경우 첫 번째 16진수 숫자는 0 이 아닙니다.
  • 값이 ​ 0 ​ 인 경우, 지수도 ​ 0 ​ 입니다.
  • 정밀도 는 16진수 소수점 문자 뒤에 나타날 정확한 자릿수를 지정합니다.
  • 기본 정밀도는 값을 정확하게 표현하기에 충분합니다.
  • 대체 구현 에서는 뒤에 숫자가 없더라도 10진수 소수점 문자가 기록됩니다.
  • 무한대 및 NaN(Not-a-Number) 변환 스타일에 대해서는 참고 사항 을 참조하십시오.
N/A N/A N/A N/A N/A N/A
g
G

부동 소수점 숫자 를 값과 정밀도 에 따라 10진수 또는 10진수 지수 표기법으로 변환합니다.

  • g 변환 스타일의 경우 e 또는 f 스타일로 변환이 수행됩니다.
  • G 변환 스타일의 경우 E 또는 f (C99 이전) F (C99 이후) 스타일로 변환이 수행됩니다.
  • P 를 정밀도가 0이 아닌 경우 정밀도 값, 정밀도가 지정되지 않은 경우 6 , 정밀도가 ​ 0 ​ 인 경우 1 으로 설정합니다. 그런 다음 E 스타일로 변환할 때 지수가 X 인 경우:
    • P > X ≥ −4 인 경우, f 또는 F (C99 이후) 스타일로 변환하며 정밀도는 P − 1 − X 입니다.
    • 그렇지 않은 경우, e 또는 E 스타일로 변환하며 정밀도는 P − 1 입니다.
  • 대체 표현 이 요청되지 않는 한 후행 영은 제거되며, 소수 부분이 남아 있지 않은 경우 소수점 문자도 제거됩니다.
  • 무한대 및 NaN(숫자가 아님) 변환 스타일에 대해서는 참고 를 확인하십시오.
N/A N/A N/A N/A N/A N/A
n

이 함수 호출로 지금까지 기록된 문자 수 를 반환합니다.

  • 결과는 인자가 가리키는 값에 기록됩니다 .
  • 지정자에는 어떠한 플래그 , 필드 너비 , 정밀도 도 포함될 수 없습니다.
  • z 수식자의 경우, 예상 인자 타입은 S * 입니다. 여기서 S 는 size_t 의 부호 있는(signed) 버전입니다.
signed char *
short *
int *
long *
long long *
※
N/A
p

구현 정의된 문자 시퀀스를 작성하여 포인터 를 정의합니다.

N/A N/A
void *
N/A N/A N/A N/A N/A N/A
참고 사항

부동 소수점 변환 함수는 무한대를 inf 또는 infinity 로 변환합니다. 어느 것을 사용할지는 구현에 따라 정의됩니다.

숫자가 아닌 값(Not-a-number)은 nan 또는 nan( char_sequence ) 로 변환됩니다. 어느 것을 사용할지는 구현에 따라 정의됩니다.

변환 지정자 F , E , G , A 는 대신 INF , INFINITY , NAN 을 출력합니다.

char , unsigned char , signed char , short , 및 unsigned short 를 출력하는 데 사용되는 변환 지정자는 기본 인수 승격 의 승격된 타입을 기대하지만, 출력하기 전에 해당 값은 char , unsigned char , signed char , short , 및 unsigned short 로 변환됩니다. 가변 인수 함수가 호출될 때 발생하는 승격으로 인해 이러한 타입의 값을 전달하는 것은 안전합니다.

고정 너비 문자 타입( int8_t 등)에 대한 올바른 변환 지정자는 헤더 <inttypes.h> 에 정의되어 있습니다(비록 PRIdMAX , PRIuMAX 등이 %jd , %ju 등과 동의어이지만).

메모리 쓰기 변환 지정자 %n 은 형식 문자열이 사용자 입력에 의존하는 보안 공격의 일반적인 대상이며 경계 검사가 수행되는 printf_s 함수군에서는 지원되지 않습니다 (C11부터) .

각 변환 지정자의 동작 이후에는 시퀀스 포인트 가 존재합니다; 이로 인해 여러 %n 결과를 동일한 변수에 저장하거나, 극단적인 경우로 동일한 호출 내에서 이전 %n 에 의해 수정된 문자열을 출력하는 것이 가능합니다.

변환 지정자가 유효하지 않은 경우, 그 동작은 정의되지 않습니다.

반환값

1,4) 성공 시 기록된 와이드 문자 수 또는 오류 발생 시 음수 값.
3) 성공 시 기록된 와이드 문자 수 또는 오류 발생 시 음수 값. 결과 문자열이 bufsz 제한으로 인해 잘리는 경우, 이 제한이 없었더라면 기록되었을 총 문자 수(종료 널 와이드 문자는 제외)를 반환합니다.
2,5) 출력 스트림으로 전송된 와이드 문자 수 또는 출력 오류, 런타임 제약 조건 위반 오류, 인코딩 오류가 발생한 경우 음수 값
6) buffer 에 기록된 와이드 문자 수(널 와이드 문자는 제외하며, 이는 buffer 가 널 포인터가 아니고 bufsz 가 0이 아니며 RSIZE_MAX/sizeof(wchar_t) 보다 크지 않은 한 항상 기록됨), 런타임 제약 조건 위반 시 0, 인코딩 오류 시 음수 값을 반환합니다.
7) 종료 null 문자(이는 항상 buffer 가 null 포인터가 아니고 bufsz 가 0이 아니며 RSIZE_MAX/sizeof(wchar_t) 보다 크지 않은 한 기록됨)를 포함하지 않는 와이드 문자 수. 이는 bufsz 가 무시되었을 경우 buffer 에 기록되었을 문자 수이거나, 런타임 제약 조건 위반 또는 인코딩 오류가 발생한 경우 음수 값입니다.

참고 사항

이 모든 함수들은 적어도 한 번 이상 va_arg 를 호출하며, 반환 후 arg 의 값은 정의되지 않습니다. 이러한 함수들은 va_end 를 호출하지 않으며, 호출자가 이를 수행해야 합니다.

좁은 문자열(narrow strings)은 필요한 출력 버퍼 크기를 결정할 수 있게 해주는 vsnprintf 를 제공하지만, 와이드 문자열(wide strings)에 대해서는 이에 상응하는 기능이 없습니다(C11의 vsnwprintf_s까지). 따라서 버퍼 크기를 결정하기 위해 프로그램은 vswprintf 를 호출하고, 결과 값을 확인한 후 더 큰 버퍼를 재할당하여 성공할 때까지 다시 시도해야 할 수 있습니다.

vsnwprintf_s 는 vswprintf_s 와 달리, 대부분의 경계 검사 함수에서 잘림을 오류로 처리함에도 불구하고 결과를 buffer 가 가리키는 배열 내에 맞도록 잘라냅니다.

예제

이 코드 실행 
#include <locale.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>
#include <time.h>
#include <wchar.h>
void debug_wlog(const wchar_t* fmt, ...)
{
    struct timespec ts;
    timespec_get(&ts, TIME_UTC);
    char time_buf[100];
    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
    va_list args;
    va_start(args, fmt);
    wchar_t buf[1024];
    int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args);
    va_end(args);
    if(rc2 > 0)
       wprintf(L"%s [debug]: %ls\n", time_buf, buf);
    else
       wprintf(L"%s [debug]: (string too long)\n", time_buf);
}
int main(void)
{
    setlocale(LC_ALL, "");
    debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3);
}

가능한 출력: 

02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3

참고문헌

  • C23 표준 (ISO/IEC 9899:2024):
  • 7.29.2.5 vfwprintf 함수 (p: TBD)
  • 7.29.2.7 vswprintf 함수 (p: TBD)
  • 7.29.2.9 vwprintf 함수 (p: TBD)
  • K.3.9.1.6 vfwprintf_s 함수 (p: TBD)
  • K.3.9.1.8 vsnwprintf_s 함수 (p: TBD)
  • K.3.9.1.9 vswprintf_s 함수 (p: TBD)
  • K.3.9.1.11 vwprintf_s 함수 (p: TBD)
  • C17 표준 (ISO/IEC 9899:2018):
  • 7.29.2.5 vfwprintf 함수 (p: TBD)
  • 7.29.2.7 vswprintf 함수 (p: TBD)
  • 7.29.2.9 vwprintf 함수 (p: TBD)
  • K.3.9.1.6 vfwprintf_s 함수 (p: TBD)
  • K.3.9.1.8 vsnwprintf_s 함수 (p: TBD)
  • K.3.9.1.9 vswprintf_s 함수 (p: TBD)
  • K.3.9.1.11 vwprintf_s 함수 (p: TBD)
  • C11 표준 (ISO/IEC 9899:2011):
  • 7.29.2.5 vfwprintf 함수 (p: 417-418)
  • 7.29.2.7 vswprintf 함수 (p: 419)
  • 7.29.2.9 vwprintf 함수 (p: 420)
  • K.3.9.1.6 vfwprintf_s 함수 (p: 632)
  • K.3.9.1.8 vsnwprintf_s 함수 (p: 633-634)
  • K.3.9.1.9 vswprintf_s 함수 (p: 634-635)
  • K.3.9.1.11 vwprintf_s 함수 (p: 636)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.24.2.5 vfwprintf 함수 (p: 363)
  • 7.24.2.7 vswprintf 함수 (p: 364)
  • 7.24.2.9 vwprintf 함수 (p: 365)

참고 항목

(C99) (C11) (C11) (C11) (C11)
서식이 지정된 출력을 stdout , 파일 스트림 또는 버퍼에 출력
가변 인수 목록 사용
(함수)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
서식이 지정된 와이드 문자 출력을 stdout , 파일 스트림 또는 버퍼에 출력
(함수)
C++ documentation for vwprintf , vfwprintf , vswprintf