1.\" 2.\" The contents of this file are subject to the terms of the 3.\" Common Development and Distribution License (the "License"). 4.\" You may not use this file except in compliance with the License. 5.\" 6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7.\" or http://www.opensolaris.org/os/licensing. 8.\" See the License for the specific language governing permissions 9.\" and limitations under the License. 10.\" 11.\" When distributing Covered Code, include this CDDL HEADER in each 12.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13.\" If applicable, add the following below this CDDL HEADER, with the 14.\" fields enclosed by brackets "[]" replaced with your own identifying 15.\" information: Portions Copyright [yyyy] [name of copyright owner] 16.\" 17.\" 18.\" Copyright 1989 AT&T 19.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. 20.\" Copyright 2016 Nexenta Systems, Inc. 21.\" 22.Dd Dec 1, 2016 23.Dt SPRINTF 9F 24.Os 25.Sh NAME 26.Nm sprintf, snprintf, vsprintf, vsnprintf 27.Nd format characters in memory 28.Sh SYNOPSIS 29.In sys/cmn_err.h 30.In sys/ddi.h 31.In sys/sunddi.h 32.Ft "char *" 33.Fo sprintf 34.Fa "char *s" 35.Fa "const char *format" 36.Fa ... 37.Fc 38.Ft size_t 39.Fo snprintf 40.Fa "char *s" 41.Fa "size_t n" 42.Fa "const char *format" 43.Fa ... 44.Fc 45.In sys/varargs.h 46.Ft "char *" 47.Fo vsprintf 48.Fa "char *s" 49.Fa "const char *format" 50.Fa "va_list ap" 51.Fc 52.Ft size_t 53.Fo vsnprintf 54.Fa "char *s" 55.Fa "size_t n" 56.Fa "const char *format" 57.Fa "va_list ap" 58.Fc 59.Sh INTERFACE LEVEL 60illumos DDI specific 61.Sh PARAMETERS 62.Bl -tag -width Ds 63.It Fa s 64Pointer to a character string. 65.It Fa n 66Size of the buffer pointed to by 67.Fa s . 68.It Fa format 69Pointer to a character string. 70.It Fa ap 71Pointer to a variable argument list. 72.El 73.Sh DESCRIPTION 74The 75.Fn sprintf 76function places output, followed by the null byte 77.Pq \e0 , 78in consecutive bytes starting at 79.Fa s ; 80it is the user's responsibility to ensure that enough storage is available. 81.Pp 82The 83.Fn snprintf 84function is identical to 85.Fn sprintf 86with the addition of the argument 87.Fa n , 88which specifies the size of the buffer referred to by 89.Fa s . 90If 91.Fa n 92is 0, nothing is written and 93.Fa s 94can be a null pointer. 95Otherwise, output bytes beyond the 96.Fa n Ns \-1st 97are discarded instead of being written to the array and a null byte is written 98at the end of the bytes actually written into the array. 99.Pp 100The 101.Fn vsprintf 102and 103.Fn vsnprintf 104functions are the same as 105.Fn sprintf 106and 107.Fn snprintf , 108respectively, except that instead of being called with a variable number of 109arguments, they are called with an argument list, 110.Fa ap , 111used by the conversion specifications in 112.Fa format . 113.Fa ap 114is a variable argument list and must be initialized by calling 115.Xr va_start 9F . 116.Xr va_end 9F 117is used to clean up and must be called after each traversal of the list. 118Multiple traversals of the argument list, each bracketed by 119.Xr va_start 9F 120and 121.Xr va_end 9F , 122are possible. 123.Pp 124Each of these functions converts, formats, and prints its arguments under 125control of the 126.Fa format . 127The 128.Fa format 129is composed of zero or more directives: ordinary characters, which are simply 130copied to the output stream and conversion specifications, each of which results 131in the fetching of zero or more arguments. 132The results are undefined if there are insufficient arguments for the 133.Fa format . 134If the 135.Fa format 136is exhausted while arguments remain, the excess arguments are evaluated but are 137otherwise ignored. 138.Ss Conversion Specifications 139Each conversion specification is introduced by the 140.Qq Sy % 141character after which the following appear in sequence: 142.Bl -bullet 143.It 144Zero or more flags 145.Pq in any order , 146which modify the meaning of the conversion specification. 147.It 148An optional minimum field width. 149If the converted value has fewer bytes than the field width, it will be padded 150with spaces by default on the left; it will be padded on the right, if the 151left-adjustment flag 152.Pq Qq Sy ‐ , 153described below, is given to the field width. 154The field width takes the form of an asterisk 155.Pq Qq Sy * , 156described below, or a decimal integer. 157.It 158An optional precision that gives the minimum number of digits to appear for the 159.Sy d , D , o , O , x , X , 160or 161.Sy u 162conversions 163.Pq the field is padded with leading zeros ; 164or the maximum number of bytes to be printed from a string in s conversion. 165The precision takes the form of a period 166.Pq Qq Sy \&. 167followed either by an asterisk 168.Pq Qq Sy * , 169described below, or an optional decimal digit string, where a null digit string 170is treated as 0. 171If a precision appears with any other conversion specifier, the behavior is 172undefined. 173.It 174An optional length modifier that specified the size of the argument. 175.It 176A conversion specifier that indicates the type of conversion to be applied. 177.El 178.Pp 179A field width, or precision, or both can be indicated by an asterisk 180.Pq Qq Sy * . 181In this case, an argument of type int supplies the field width or precision. 182Arguments specifying field width, or precision, or both must appear in that 183order before the argument, if any, to be converted. 184A negative field width is taken as a 185.Qq Sy \- 186flag followed by a positive field width. 187A negative precision is taken as if the precision were omitted. 188.Ss Flag Characters 189The flag characters and their meanings are: 190.Bl -tag -width Ds 191.It Sy \- 192The result of the conversion will be left-justified within the field. 193The conversion will be right-justified if this flag is not specified. 194.It Sy 0 195For 196.Sy d , D , o , O , x , X , 197or 198.Sy u 199conversions, leading zeros 200.Pq following any indication of sign or base 201are used to pad to the field width; no space padding is performed. 202If the 203.Sy 0 204and 205.Sy \- 206flags both appear, the 207.Sy 0 208flag will be ignored. 209If a precision is specified, the 210.Sy 0 211flag will be ignored. 212For other conversions, the behavior is undefined. 213.El 214.Ss Length Modifiers 215The length modifiers and their meanings are: 216.Bl -tag -width Ds 217.It Sy h 218Specifies that a following 219.Sy d , D , o , O , x , X , 220or 221.Sy u 222conversion specifier applies to a short or unsigned 223short argument 224.Po the argument will have been promoted according to the integer promotions, 225but its value will be converted to short or unsigned short before printing 226.Pc . 227.It Sy hh 228Specifies that a following 229.Sy d , D , o , O , x , X , 230or 231.Sy u 232conversion specifier applies to a signed char or unsigned char argument 233.Po the argument will have been promoted according to the integer promotions, 234but its value will be converted to signed char or unsigned char before printing 235.Pc . 236.It Sy l 237Specifies that a following 238.Sy d , D , o , O , x , X , 239or 240.Sy u 241conversion specifier applies to a long or unsigned long argument. 242.It Sy ll 243Specifies that a following 244.Sy d , D , o , O , x , X , 245or 246.Sy u 247conversion specifier applies to a long long or unsigned long long argument. 248.El 249.Ss Conversion Specifiers 250Each conversion specifier results in fetching zero or more arguments. 251The results are undefined if there are insufficient arguments for the 252.Fa format . 253If the 254.Fa format 255is exhausted while arguments remain, the excess arguments are ignored. 256.Pp 257The conversion specifiers and their meanings are: 258.Bl -tag -width Ds 259.It Sy d , D , o , O , x , X , u 260The integer argument is converted to signed decimal 261.Pq Sy d , D , 262unsigned octal 263.Pq Sy o , O , 264unsigned hexadecimal 265.Pq Sy x , X , 266or unsigned decimal 267.Pq Sy u , 268respectively. 269The letters 270.Qq Sy abcdef 271are used for 272.Sy x 273and letters 274.Qq Sy ABCDEF 275for 276.Sy X 277conversions. 278.It Sy c 279The character value of the argument is printed. 280.It Sy b 281The 282.Sy %b 283conversion specification allows bit values to be printed meaningfully. 284Each 285.Sy %b 286takes an integer value and a format string from the argument list. 287The first character of the format string should be the output base encoded as a 288control character. 289This base is used to print the integer argument. 290The remaining groups of characters in the format string consist of a bit number 291.Pq between 1 and 32, also encoded as a control character 292and the next characters 293.Pq up to the next control character or '\e0' 294give the name of the bit field. 295The string corresponding to the bit fields set in the integer argument is 296printed after the numerical value. 297.It Sy p 298The argument is taken to be a pointer; the value of the pointer is printed in 299unsigned hexadecimal. 300The print format is equivalent to 301.Sy %lx . 302To avoid lint warnings, cast pointers to type 303.Ft "void *" 304when using the 305.Sy %p 306format specifier. 307.It Sy s 308The argument is taken to be a string 309.Pq character pointer , 310and characters from the string are printed until a null character is ecountered. 311If the character pointer is 312.Sy NULL , 313the string 314.Qq <null string> 315is used in its place. 316.It Sy % 317Copy a 318.Sy % ; 319no argument is converted. 320.El 321.Sh CONTEXT 322These functions can be called from user, kernel, interrupt, or 323high-level interrupt context. 324.Sh RETURN VALUES 325.Fn sprintf 326and 327.Fn vsprintf 328return 329.Fa s . 330.Pp 331.Fn snprintf 332and 333.Fn vsnprintf 334return the number of bytes that would have been written to 335.Fa s 336if 337.Fa n 338had been sufficiently large 339.Pq excluding the terminating null byte . 340.Sh SEE ALSO 341.Xr cmn_err 9F , 342.Xr va_arg 9F , 343.Xr va_end 9F , 344.Xr va_start 9F 345