quote.3 (2884B)
1 .TH QUOTE 3 2 .SH NAME 3 quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, fmtdoquote \- quoted character strings 4 .SH SYNOPSIS 5 .B #include <utf.h> 6 .br 7 .B #include <fmt.h> 8 .PP 9 .B 10 char *quotestrdup(char *s) 11 .PP 12 .B 13 Rune *quoterunestrdup(Rune *s) 14 .PP 15 .B 16 char *unquotestrdup(char *s) 17 .PP 18 .B 19 Rune *unquoterunestrdup(Rune *s) 20 .PP 21 .B 22 int quotestrfmt(Fmt*) 23 .PP 24 .B 25 int quoterunestrfmt(Fmt*) 26 .PP 27 .B 28 void quotefmtinstall(void) 29 .PP 30 .B 31 int (*fmtdoquote)(int c) 32 .PP 33 .SH DESCRIPTION 34 These routines manipulate character strings, either adding or removing 35 quotes as necessary. 36 In the quoted form, the strings are in the style of 37 .IR rc (1) , 38 with single quotes surrounding the string. 39 Embedded single quotes are indicated by a doubled single quote. 40 For instance, 41 .IP 42 .EX 43 Don't worry! 44 .EE 45 .PP 46 when quoted becomes 47 .IP 48 .EX 49 \&'Don''t worry!' 50 .EE 51 .PP 52 The empty string is represented by two quotes, 53 .BR '' . 54 .PP 55 The first four functions act as variants of 56 .B strdup 57 (see 58 .IR strcat (3)). 59 Each returns a 60 freshly allocated copy of the string, created using 61 .IR malloc (3). 62 .I Quotestrdup 63 returns a quoted copy of 64 .IR s , 65 while 66 .I unquotestrdup 67 returns a copy of 68 .IR s 69 with the quotes evaluated. 70 The 71 .I rune 72 versions of these functions do the same for 73 .CW Rune 74 strings (see 75 .IR runestrcat (3)). 76 .PP 77 The string returned by 78 .I quotestrdup 79 or 80 .I quoterunestrdup 81 has the following properties: 82 .TP 83 1. 84 If the original string 85 .IR s 86 is empty, the returned string is 87 .BR '' . 88 .TP 89 2. 90 If 91 .I s 92 contains no quotes, blanks, or control characters, 93 the returned string is identical to 94 .IR s . 95 .TP 96 3. 97 If 98 .I s 99 needs quotes to be added, the first character of the returned 100 string will be a quote. 101 For example, 102 .B hello\ world 103 becomes 104 .B \&'hello\ world' 105 not 106 .BR hello'\ 'world . 107 .PP 108 The function pointer 109 .I fmtdoquote 110 is 111 .B nil 112 by default. 113 If it is non-nil, characters are passed to that function to see if they should 114 be quoted. 115 This mechanism allows programs to specify that 116 characters other than blanks, control characters, or quotes be quoted. 117 Regardless of the return value of 118 .IR *fmtdoquote , 119 blanks, control characters, and quotes are always quoted. 120 .I Needsrcquote 121 is provided as a 122 .I fmtdoquote 123 function that flags any character special to 124 .IR rc (1). 125 .PP 126 .I Quotestrfmt 127 and 128 .I quoterunestrfmt 129 are 130 .IR print (3) 131 formatting routines that produce quoted strings as output. 132 They may be installed by hand, but 133 .I quotefmtinstall 134 installs them under the standard format characters 135 .B q 136 and 137 .BR Q . 138 (They are not installed automatically.) 139 If the format string includes the alternate format character 140 .BR # , 141 for example 142 .BR %#q , 143 the printed string will always be quoted; otherwise quotes will only be provided if necessary 144 to avoid ambiguity. 145 .SH SOURCE 146 .B https://9fans.github.io/plan9port/unix 147 .SH "SEE ALSO 148 .IR rc (1), 149 .IR malloc (3), 150 .IR print (3), 151 .IR strcat (3)