1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
/* vi: set sw=4 ts=4:
*
* split.h
*
* Function that splits a string intro arguments with quoting.
*
* by Nick Patavalis (npat@efault.net)
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
* USA
*/
#ifndef SPLIT_H
#define SPLIT_H
/* Maximum single-argument length that can be dealt-with by function
* split_quoted(). Longer arguments are truncated. See below.
*/
#define MAX_ARG_LEN 512
/* Warning flags, set by split_quoted() to its return value. */
#define SPLIT_DROP (1 << 0) /* argument had to be dropped */
#define SPLIT_TRUNC (1 << 1) /* argument had to be truncated */
/* F split_quoted
*
* Splits string "s" into arguments and places them in "argv". Every
* argument is a heap-allocated null-terminated string that must be
* freed with free(3) when no longer needed. The first argument is
* placed in "argv[*argc]", the following at subsequent "argv" slots,
* and "*argc" is incremented accordingly. As a result, this function
* can be called multiple times to add arguments to the same argument
* vector. The argument "argv_sz" is the allocated size (in number of
* slots) of the supplied argument vector ("argv"). The function takes
* care not to overrun it. If more arguments are present in the
* input string "s", they are dropped.
*
* When spliting the input string intro arguments, quoting rules
* very similar to the ones used by the Unix shell are used.
*
* The following caracters are considered special: ' ' (space), '\t'
* (tab), '\n' (newline), '\' (backslash), ''' (single quote), and '"'
* (double quote). All other caracters are considered normal and can
* become part of an argument without escaping.
*
* Arguments are separated by runs of the characters: ' ' (space),
* '\t', and '\n', which are considered delimiters.
*
* All characters beetween single quotes (')---without
* exceptions---are considered normal and become part of the current
* argument (but not the single quotes themselves).
*
* All characters between double quotes (") are considered normal and
* become part of the current argument (but not the double quotes
* themselves). Exception to this is the backslash character, when
* followed by one of the characters '"', '\', '$', and '`'. In this
* case, the backslash is removed, and the next caracter is considered
* normal and becomes part of the current argument. When the backslash
* is followed by newline, both the backslash and the newline are
* removed. In all other cases a backslash, within double quotes, is
* considered a normal character (and becomes part of the current
* argument). We treat the sequences '\$' and '\`' specially (while
* there is no real reason), for better unix-shell compatibility.
*
* Outside of single or double quotes, every backslash caracter is
* removed, and the following character (with the exception of
* <newline>, see below) is considered normal and becomes part of the
* current argument. If, outside of quotes, a backslash precedes a
* <newline>, then both the backslash and the newline are removed.
*
* Examples:
*
* a b c d --> [a] [b] [c] [d]
* 'a b' c d --> [a b] [c] [d]
* 'a "b"' c d --> [a "b"] [c] [d]
* "a 'b'" c d --> [a 'b'] [c] [d]
* a"b c" d --> [ab c] [d]
* a\ b c d --> [a b] [c] [d]
* \a\b c d --> [ab] [c] [d]
* \a\\b \\ c d --> [a\b] [\] [c] [d]
* "a\$\b" c d --> [a$\b] [c] [d]
* "\a\`\"\b" c d --> [\a`"\b] [c] [d]
*
* Limitation: This function cannot deal with individual arguments
* longer than MAX_ARG_LEN. If such an argument is encountered, it is
* truncated accordingly.
*
* This function returns a non-negative on success, and a negative on
* failure. The only causes for failure is a malformed command string
* (e.g. un-balanced quotes), or the inability to allocate an argument
* string. On success the value returned can be checked against the
* warning flags SPLIT_DROP, and SPLIT_TRUNC. If SPLIT_DROP is set,
* then a least one argument was dropped as there was no available
* slot in "argv" to store it in. If SPLIT_TRUNC is set, then at least
* one argument was truncated (see limitation, above).
*/
int split_quoted(const char *s, int *argc, char *argv[], int argv_sz);
#endif /* of SPLIT_H */
/**********************************************************************/
/*
* Local Variables:
* mode:c
* tab-width: 4
* c-basic-offset: 4
* indent-tabs-mode: nil
* End:
*/
|
