quote.3 (3210B)
1 .TH QUOTE 3 2 .SH NAME 3 quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote \- quoted character strings 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.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 (*doquote)(int c) 32 .PP 33 .B 34 int needsrcquote(int c) 35 .PP 36 .SH DESCRIPTION 37 These routines manipulate character strings, either adding or removing 38 quotes as necessary. 39 In the quoted form, the strings are in the style of 40 .IR rc (1) , 41 with single quotes surrounding the string. 42 Embedded single quotes are indicated by a doubled single quote. 43 For instance, 44 .IP 45 .EX 46 Don't worry! 47 .EE 48 .PP 49 when quoted becomes 50 .IP 51 .EX 52 \&'Don''t worry!' 53 .EE 54 .PP 55 The empty string is represented by two quotes, 56 .BR '' . 57 .PP 58 The first four functions act as variants of 59 .B strdup 60 (see 61 .MR strcat (3) ). 62 Each returns a 63 freshly allocated copy of the string, created using 64 .MR malloc (3) . 65 .I Quotestrdup 66 returns a quoted copy of 67 .IR s , 68 while 69 .I unquotestrdup 70 returns a copy of 71 .IR s 72 with the quotes evaluated. 73 The 74 .I rune 75 versions of these functions do the same for 76 .CW Rune 77 strings (see 78 .MR runestrcat (3) ). 79 .PP 80 The string returned by 81 .I quotestrdup 82 or 83 .I quoterunestrdup 84 has the following properties: 85 .TP 86 1. 87 If the original string 88 .IR s 89 is empty, the returned string is 90 .BR '' . 91 .TP 92 2. 93 If 94 .I s 95 contains no quotes, blanks, or control characters, 96 the returned string is identical to 97 .IR s . 98 .TP 99 3. 100 If 101 .I s 102 needs quotes to be added, the first character of the returned 103 string will be a quote. 104 For example, 105 .B hello\ world 106 becomes 107 .B \&'hello\ world' 108 not 109 .BR hello'\ 'world . 110 .PP 111 The function pointer 112 .I doquote 113 is 114 .B nil 115 by default. 116 If it is non-nil, characters are passed to that function to see if they should 117 be quoted. 118 This mechanism allows programs to specify that 119 characters other than blanks, control characters, or quotes be quoted. 120 Regardless of the return value of 121 .IR *doquote , 122 blanks, control characters, and quotes are always quoted. 123 .I Needsrcquote 124 is provided as a 125 .I doquote 126 function that flags any character special to 127 .MR rc (1) . 128 .PP 129 .I Quotestrfmt 130 and 131 .I quoterunestrfmt 132 are 133 .MR print (3) 134 formatting routines that produce quoted strings as output. 135 They may be installed by hand, but 136 .I quotefmtinstall 137 installs them under the standard format characters 138 .B q 139 and 140 .BR Q . 141 (They are not installed automatically.) 142 If the format string includes the alternate format character 143 .BR # , 144 for example 145 .BR %#q , 146 the printed string will always be quoted; otherwise quotes will only be provided if necessary 147 to avoid ambiguity. 148 In 149 .B <libc.h> 150 there are 151 .B #pragma 152 statements so the compiler can type-check uses of 153 .B %q 154 and 155 .B %Q 156 in 157 .MR print (3) 158 format strings. 159 .SH SOURCE 160 .B \*9/src/lib9/quote.c 161 .br 162 .B \*9/src/lib9/fmt/fmtquote.c 163 .SH "SEE ALSO 164 .MR rc (1) , 165 .MR malloc (3) , 166 .MR print (3) , 167 .MR strcat (3) 168 .SH BUGS 169 Because it is provided by the format library, 170 .I doquote 171 is a preprocessor macro defined as 172 .IR fmtdoquote ; 173 see 174 .MR intro (3) .