getCGIparm(3) FreeBSD Library Functions Manual getCGIparm(3) NAME getCGIparmpass1, getCGIparmpass2, getCGIparmpass3, getCGIparmpass4, getCGIparmcopy, getCGIparmenv, getCGIparmarray, getCGIparmopt, getCGIparmproc -- Безопасный ввод параметров в cgi программах LIBRARY library ``libgetCGIparm'' SYNOPSIS #include #include #include int getCGIparmpass1(u_int32_t flags, const u_char **query, const u_char *tofind, u_char *unescaped); int getCGIparmpass2(u_int32_t flags, const u_char *pattern, const u_char *unescaped); int getCGIparmpass3(u_int32_t flags, const u_char *quoten, u_char **unescaped); void getCGIparmpass4(u_int32_t flags, const u_char *pattern, const u_char *tofind, u_char *errmsg, u_char *errfile, u_char *errform, FILE *errout); int getCGIparmcopy(u_int32_t flags, const u_char *query, const u_char *pattern, const u_char *query_delimit, const u_char *null_sign, int outf); int getCGIparmenv(u_int32_t flags, const u_char **envp, const u_char *pattern, const u_char *query_delimit, const u_char *null_sign, int outf); int getCGIparmarray(u_int32_t flags, const u_char **args, const u_char *pattern, const u_char *query_delimit, const u_char *null_sign, int outf); int getCGIparmopt(u_int32_t flags, const u_char *opts, const u_char *pattern, const u_char *query_delimit, const u_char *null_sign, int outf); int getCGIparmproc(u_int32_t flags, const u_char *pattern, const u_char *query_delimit, const u_char *null_sign, int outf); DESCRIPTION Функция getCGIparmpass1() извлекает в unescaped из query первое имеющееся значение параметра, заданного в tofind. Если tofind == NULL, то извлека- ется первый кортеж. query после исполнения getCGIparmpass1() устанавли- вается на конец использованного кортежа. unescaped перед исполнением функции должен указывать на массив достаточного для размещения результата размера. При успехе возвращает нулевое значение, или если установлен флаг gCGI_SEPR и найден знак `=', то смещение значения относительно начала кортежа. При неуспехе в unescaped заносится строка нулевой длинны и результат функции меньше нуля. Входная строка представляет собой параметр, который передается командами GET или POST через apache для CGI. Кортежи в нем ограничены символами `&', имя параметра содержится между началом кортежа и первым символом `='. На результат влияют биты gCGI_NOCR, gCGI_NOLF и gCGI_SEPR в пара- метре flags. getCGIparmpass2() проверяет, что unescaped содержит параметр типа, задан- ного pattern. Список распознаваемых pattern можно посмотреть командой getCGIparm -h, описания их в getCGIparm(1). Если unescaped удовлетворяет условию pattern то возвращает нулевое значение, иначе не ноль. На результат влияет бит gCGI_NONL в параметре flags. getCGIparmpass3() заменяет строку unescaped на обработанную в соответ- ствии с quoten. Список распознаваемых quoten можно посмотреть момандой getCGIparm -h, описания их в getCGIparm(1). На результат влияет бит gCGI_ZERO в параметре flags. getCGIparmpass4() выдает в errout сообщение. Если errmsg не NULL, то выдается эта строка, иначе, если errfile не NULL, то выдается содержимое этого файла, иначе errform содержит варианты сообщений в зависимости от вида pattern и имени tofind вводимого параметра. Подробное описание getCGIparm(1) см. описание -e. На результат влияют биты gCGI_OTST, gCGI_TEXT, gCGI_FILE, gCGI_FORM и gCGI_OPEN в параметре flags. getCGIparmcopy(), getCGIparmenv(), getCGIparmarray(), getCGIparmopt() выдают параметры и их значения в формате COPY PostgreSQL. Если установ- лен бит gCGI_RNUM в параметре flags, то в качестве самой левой колонки добавляется порядковый номер, начиная с 0. Особенности именования пара- метра в выдаче getCGIparmarray() описаны ниже. pattern содержит описание допустимого формата параметров, query_delimit - это та строка, которая разделяет колонки в COPY (обычно это символ горизонтальной табуляции), null_sign - это строка, представляющая значение NULL (обычно это \N), outf - дескриптор выходного файла. На результат также влияет бит gCGI_OTST в параметре flags. getCGIparmcopy() выдает параметры из формата параметров запроса apache. query содержит строку запроса. Кортежи в запросе разделены незакодирован- ными амперсандами, каждому кортежу соответствует выходная строка, если в кортеже имеется незакодированный знак равенства, то все, что слева от самого левого незакодированного знака равенства, является именем пара- метра, а все, что справа от самого левого знака равенства в кортеже - значение параметра. Если кортеж начинается с незакодированного знака равенства, то имя параметра - пустая строка. Если кортеж оканчивается незакодированным знаком равенства, и другого в этом кортеже нет, то зна- чение параметра - пустая строка. Если в кортеже нет незакодированного знака равенства, то имя параметра NULL, а значение - весь кортеж. И имена, и значения параметров выдаются в декодированном виде. getCGIparmenv() выдает параметры из environment. envp содержит ссылку на переменные окружения. getCGIparmarray() выдает параметры из формата, совместимого с массивом параметров execv. Вместо имени параметра выдается его порядковый номер, начиная с 0, если бит gCGI_RNUM сброшен, и NULL - если установлен. args содержит ссылку на параметры. getCGIparmopt() выдает опции, заданные в командной строке. Имя параметра - это буква, задающая опцию, аргумент опции выдается в качестве значения, если эта опция помечена : в opts, в соответствии с getopt(3), или NULL, если опция без аргумента. На результат влияют биты gCGI_OTST, gCGI_RNUM и gCGI_EOPT в параметре flags. getCGIparmproc() выдает для всех запущенных в системе процессов три колонки в формате COPY PostgreSQL: номер процесса, номер параметра, текст параметра. На результат влияет бит gCGI_OTST в параметре flags. FLAGS Параметр flags - битовый массив. Его биты: #define gCGI_DOER 0x00000001 #define gCGI_MATC 0x00000002 #define gCGI_NONL 0x00000004 #define gCGI_ERRMASK 0x00000007 #define gCGI_RNUM 0x00000008 #define gCGI_TEXT 0x00000010 #define gCGI_FILE 0x00000020 #define gCGI_FORM 0x00000040 #define gCGI_OUTMASK 0x00000070 #define gCGI_NOCR 0x00000100 #define gCGI_NOLF 0x00000200 #define gCGI_OTST 0x00000400 #define gCGI_ZERO 0x00000800 #define gCGI_EOPT 0x00002000 #define gCGI_OPEN 0x00004000 #define gCGI_SEPR 0x00008000 #define BLIN_VER1 0x01000000 #define BLIN_VER2 0x02000000 #define BLIN_VER3 0x04000000 #define BLIN_VER4 0x08000000 gCGI_DOER заданный параметр не найден. gCGI_MATC параметр не соответствует образцу. gCGI_NONL заданный параметр пуст. gCGI_RNUM при выдаче таблицы в формате COPY PostgreSQL первой колонкой выдается номер строки. gCGI_TEXT сообщение об ошибке задано. gCGI_FILE имя файта с сообщением об ошибке задано. gCGI_FORM имя файла с вариантами сообщений об ошибке задано. gCGI_NOCR не выводить CR. gCGI_NOLF не выводить LF. gCGI_OTST тестовый режим, не выводить ничего. gCGI_ZERO пустое значение параметра будет заменено. gCGI_EOPT Не заменять неизвестные флаги на `?' и не выводить сообщение об ошибке, вводить их как флаги без параметров. gCGI_OPEN в конце образца при проверке стоит `*'. gCGI_SEPR отделять имя параметра от значения. Без этого флага кортеж ПредыдущиеКортежи&имя=значение&ОстальныеКортежи введется как параметр без имени со значением имя=значение а с этим флагом имя и значение параметра в кортеже будут раз- делены. BLIN_VER1 включает печать сообщений в stderr об ошибках. BLIN_VER2 и выше предназначены для отладки. Остальные поля должны быть установлены в 0. PATTERNS Параметр pattern задает допустимые значения параметра. Его значения: [символы] значением может быть строка, составленная только из указанных между квадратными скобками символов. Можно использовать `^' и `-' привычным по re_format(7) образом. any нет ограничений на значение параметра. КОИ8 кои8 в параметре могут быть только определенные в KOI8-R символы. ASCII ascii в параметре могут быть только определенные в ASCII символы. macaddr параметр - MAC адрес, в котором октеты разделены двоеточием. inetaddr параметр - IPv4 адрес. inetnet параметр - IPv4 сеть в CIDR записи, маска необязательна. =строка параметром может быть только в точности та строка, что задана после знака равенства. date Параметр - дата в формате YYYY-MM-DD. QUOTENS Параметр quoten задает выходное представление параметра. psql все обратные слэши и одинарные кавычки удваиваются. psqi все обратные слэши и двойные кавычки удваиваются. copy кодируется в приемлемый для оператора COPY PostgreSQL вид. sq параметр заключается в одинарные кавычки. dq параметр заключается в двойные кавычки. Разные QUOTENS можно комбинировать, указывая их в порядке применения. В комбинированной строке QUOTENS между элементами ставится знак `/'. Например, при вводе допустимого идентификатора PostgreSQL quoten задается так: `psqi/dq'. RETURN VALUES getCGIparmpass1() при успехе перемещает query в конец найденного кортежа, и возвращает 0 в качестве результата, больше нуля, если задан флаг gCGI_SEPR и обнаружено имя параметра. В этом случае результат есть длинна имени параметра вместе с заключительным знаком равенства, и меньше 0, если при выполнении встретилась ошибка, модуль этого значения см. sysexits(3). getCGIparmpass2(), getCGIparmpass3() возвращают 0 при успехе и не 0, если при выполнении встретилась ошибка, см. sysexits(3). getCGIparmcopy(), getCGIparmenv(), getCGIparmarray(), getCGIparmproc() возвращают 0 при успехе и не 0, если при выполнении встретилась ошибка, см. sysexits(3). getCGIparmopt() при ошибке возвращает положительный код ошибки, см. sysexits(3), или минус количество слов, опознанных как опции. SEE ALSO getCGIparm(1), postmaster(1), sysexits(3), getopt(3), ascii(7). BUGS Состав типов, которые можно задавать аргументом pattern фиксирован и не может быть изменен иначе, как трансляцией. Все фильтры quoten являются частью библиотеки и их состав не может быть изменен иначе, как трансляцией. getCGIparmpass3() самостоятельно может сделать malloc() для своего аргу- мента unescaped. А может и не сделать. AUTHOR Aleksandr A. Babaylov (aka @BABOLO) .@babolo.ru http://www.babolo.ru/ 03 November 2003