.\" -*- coding: UTF-8 -*- .\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk .\" .\" .\" %%%LICENSE_START(GPLv2+_DOC_FULL) .\" This is free documentation; 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. .\" .\" The GNU General Public License's references to "object code" .\" and "executables" are to be interpreted as the output of any .\" document formatting or typesetting system, including .\" intermediate and printed output. .\" .\" This manual 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 manual; if not, see .\" . .\" %%%LICENSE_END .\" .\" References consulted: .\" SunOS 4.1.1 man pages .\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt .\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998 .\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb .\" 2008-09-02, mtk: various additions and rewrites .\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from .\" Timothy S. Nelson .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH HSEARCH 3 "1 ноября 2020 г." GNU "Руководство программиста Linux" .SH ИМЯ hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- операции над ассоциативными массивами .SH СИНТАКСИС .nf \fB#include \fP .PP \fBint hcreate(size_t \fP\fInel\fP\fB);\fP .PP \fBENTRY *hsearch(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB);\fP .PP \fBvoid hdestroy(void);\fP .PP \fB#define _GNU_SOURCE\fP /* смотрите feature_test_macros(7) */ \fB#include \fP .PP \fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP .PP \fBint hsearch_r(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB, ENTRY **\fP\fIretval\fP\fB,\fP \fB struct hsearch_data *\fP\fIhtab\fP\fB);\fP .PP \fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP .fi .SH ОПИСАНИЕ Функции \fBhcreate\fP(), \fBhsearch\fP() и \fBhdestroy\fP() позволяют создать и работать с ассоциативным массивом поиска (хэшем), который содержит элементы, состоящие из ключа (строки) и связанных с ним данных. Функции позволяют работать одномоментно только с одним массивом. .PP Функции \fBhcreate_r\fP(), \fBhsearch_r\fP() и \fBhdestroy_r\fP() являются реентерабильными версиями, позволяющими программе создавать более одного массива поиска одномоментно. Последний параметр, \fIhtab\fP, указывает на структуру, описывающую массив, с которым работает функция. Программист должен считать, что не знает её формат (т. е., не должен пытаться напрямую читать и изменять её поля). .PP .\" e.g., in glibc it is raised to the next higher prime number Сначала, хэш должен быть создан с помощью функции \fBhcreate\fP(). В аргументе \fInel\fP указывается предполагаемое максимальное количество элементов в массиве (данный максимум нельзя изменить позже, указывайте значение с запасом). Реализация функции может изменить этот параметр для повышения быстродействия массива. .PP Функция \fBhcreate_r\fP() выполняет тоже, что и \fBhcreate\fP(), но для массива, описанного в структуре \fI*htab\fP. Перед вызовом \fBhcreate_r\fP() структура, на которую указывает \fIhtab\fP, должна быть обнулена. .PP Функция \fBhdestroy\fP() освобождает память, занимаемую массивом, созданным \fBhcreate\fP(). После вызова \fBhdestroy\fP() функцией \fBhcreate\fP() можно создать новый массив. Функция \fBhdestroy_r\fP() выполняет аналогичную задачу для массива, описанного в \fI*htab\fP, который был ранее создан \fBhcreate_r\fP(). .PP Функция \fBhsearch\fP() ищет в массиве элемент с ключом, равным \fIitem\fP («равенство» определяется функцией \fBstrcmp\fP(3)), и, в случае удачного завершения операции, возвращает указатель на него. .PP Аргумент \fIitem\fP имеет тип \fIENTRY\fP, который определён в \fI\fP следующим образом: .PP .in +4n .EX typedef struct entry { char *key; void *data; } ENTRY; .EE .in .PP Поле \fIkey\fP указывает на оканчивающуюся null строку, используемую в качестве ключа для поиска. Поле \fIdata\fP указывает на данные, связанные с ключом. .PP Аргумент \fIaction\fP определяет действие, выполняемое \fBhsearch\fP() после неудачного поиска. Его значением должно быть \fBENTER\fP (указывает, что нужно вставить копию \fIitem\fP и вернуть указатель на новый элемент массива) или \fBFIND\fP (нужно вернуть NULL). Если значение \fIaction\fP равно \fBFIND\fP, то поле \fIdata\fP игнорируется. .PP Функция \fBhsearch_r\fP() подобна \fBhsearch\fP(), но работает с массивом, указанным в \fI*htab\fP. Функция \fBhsearch_r\fP() отлична от \fBhsearch\fP() в том, что указатель найденного элемента возвращается в \fI*retval\fP, а не как результат работы функции. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" Функции \fBhcreate\fP() и \fBhcreate_r\fP() возвращают ненулевое значение при успешном выполнении. При ошибке возвращается 0, а \fIerrno\fP устанавливается в соответствующее значение. .PP Функция \fBhsearch\fP() при успешном выполнении возвращает указатель на элемент массива. При ошибке возвращается NULL, то есть, если \fIaction\fP равно \fBENTER\fP массив полон, или, если \fIaction\fP равно \fBFIND\fP и \fIitem\fP не может быть найден в массиве. Функция \fBhsearch_r\fP() возвращает 0 в случае ошибки или ненулевое значение при успешном выполнении. При ошибке данные функции присваивают \fIerrno\fP код ошибки. .SH ОШИБКИ Функции \fBhcreate_r\fP() и \fBhdestroy_r\fP() могут завершиться с ошибкой по следующим причинам: .TP \fBEINVAL\fP Значение \fIhtab\fP равно NULL. .PP Функции \fBhsearch\fP() и \fBhsearch_r\fP() могут завершиться с ошибкой по следующим причинам: .TP \fBENOMEM\fP Значение \fIaction\fP равно \fBENTER\fP, значение \fIkey\fP не найдено в массиве и в массиве нет места под новый элемент. .TP \fBESRCH\fP Значение \fIaction\fP равно \fBFIND\fP и значение \fIkey\fP не найдено в массиве. .PP .\" PROX.1-2001, POSIX.1-2008 В POSIX.1 определена только ошибка \fBENOMEM\fP. .SH АТРИБУТЫ Описание терминов данного раздела смотрите в \fBattributes\fP(7). .TS allbox; lbw25 lb lb l l l. Интерфейс Атрибут Значение T{ \fBhcreate\fP(), \fBhsearch\fP(), .br \fBhdestroy\fP() T} Безвредность в нитях MT\-Unsafe race:hsearch T{ \fBhcreate_r\fP(), \fBhsearch_r\fP(), .br \fBhdestroy_r\fP() T} Безвредность в нитях MT\-Safe race:htab .TE .SH "СООТВЕТСТВИЕ СТАНДАРТАМ" Функции \fBhcreate\fP(), \fBhsearch\fP() и \fBhdestroy\fP() взяты из SVr4 и описаны в POSIX.1\-2001 и POSIX.1\-2008. .PP Функции \fBhcreate_r\fP(), \fBhsearch_r\fP() и \fBhdestroy_r\fP() являются расширениями GNU. .SH ЗАМЕЧАНИЯ Реализации ассоциативных массивов более эффективны, если массив содержит достаточно свободного места, чтобы не искать незанятое пространство. Это означает, что обычно, значение \fInel\fP нужно увеличить на, как минимум, 25% от максимального количества элементов, ожидаемых в массиве. .PP Функции \fBhdestroy\fP() и \fBhdestroy_r\fP() не освобождают буферы, на которые указывают элементы \fIkey\fP и \fIdata\fP в массиве (это невозможно сделать, так как неизвестно, были ли выделены эти буферы динамически). Если эти буферы требуется освобождать (возможно, из\-за того, что программа много раз создаёт и удаляет массивы, а не создаёт один массив на всё время работы), то программа должна предусмотреть хранилище под используемые структуры, которое позволило бы их освободить. .SH ДЕФЕКТЫ В SVr4 и POSIX 1003.1\-2001 указано, что \fIaction\fP имеет смысл только при неудачном поиске, поэтому при \fBENTER\fP не нужно ничего делать, если что\-то найдено. В библиотеках libc и glibc (до версии 2.3) реализация функций обновляет \fIdata\fP для указанного \fIkey\fP в этом случае. .PP Можно добавлять элементы массива, но не удалять. .SH ПРИМЕРЫ Следующая программа вставляет в массив 24 элемента, а затем выводит на печать некоторые из них: .PP .EX #include #include #include static char *data[] = { "alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel", "india", "juliet", "kilo", "lima", "mike", "november", "oscar", "papa", "quebec", "romeo", "sierra", "tango", "uniform", "victor", "whisky", "x\-ray", "yankee", "zulu" }; int main(void) { ENTRY e; ENTRY *ep; hcreate(30); for (int i = 0; i < 24; i++) { e.key = data[i]; /* data is just an integer, instead of a pointer to something */ e.data = (void *) i; ep = hsearch(e, ENTER); /* there should be no failures */ if (ep == NULL) { fprintf(stderr, "entry failed\en"); exit(EXIT_FAILURE); } } for (int i = 22; i < 26; i++) { /* print two entries from the table, and show that two are not in the table */ e.key = data[i]; ep = hsearch(e, FIND); printf("%9.9s \-> %9.9s:%d\en", e.key, ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0); } hdestroy(); exit(EXIT_SUCCESS); } .EE .SH "СМ. ТАКЖЕ" \fBbsearch\fP(3), \fBlsearch\fP(3), \fBmalloc\fP(3), \fBtsearch\fP(3) .SH ЗАМЕЧАНИЯ Эта страница является частью проекта Linux \fIman\-pages\fP версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу \%https://www.kernel.org/doc/man\-pages/. .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .