From patchwork Wed May 8 19:59:01 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 1097204 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=sourceware.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=libc-alpha-return-101866-incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.b="ybvtIoip"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 44znNw1DHJz9s9T for ; Thu, 9 May 2019 05:59:11 +1000 (AEST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:date:message-id:from:to:subject; q=dns; s= default; b=Nw4gR0y9mUigNedy4UWuhNTBnijfTq9Znw0bGQ5ty/Suf++IdixP1 BZPqwWtnBFNp0628Edd4HLRpzbhjZ1MmNYHgEXby1GI4OPfjThsVKh/Xt2MgVEVh 1mKjJSFuDbiNq3j03J4P5YRLT1BsXkjkwXmSLnTixwsaqV3DsG+y+U= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:date:message-id:from:to:subject; s=default; bh=0JOGgHNGgYttTGbwOUeQh2yruoU=; b=ybvtIoipcHJRcGAXa614sIiktN3T wiWLuBgmlMRGkfWyS7w2RAFLdmBlOxkEGir3bRI0rk2EWwrtAJGgsRs9TwPGbqSr Abl7sSTUgr2KsXt3sYbGzC8E7ioYSFt05P1+/So1kIxoMFMz+5WAnhCDkJLv5nIf ICRwfBpF8W+Xmbk= Received: (qmail 24764 invoked by alias); 8 May 2019 19:59:06 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 24756 invoked by uid 89); 8 May 2019 19:59:05 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-17.0 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_HELO_PASS autolearn=ham version=3.3.1 spammy=nis, nsswitch.conf, nsswitchconf, UD:conf X-HELO: mx1.redhat.com Date: Wed, 08 May 2019 15:59:01 -0400 Message-Id: From: DJ Delorie To: libc-alpha@sourceware.org Subject: [patch-ish, WIP] Enhance comments in nsswitch.h In an attempt to understand how nsswitch.c operates, I've updated the comments in nsswitch.h to act more as a guide-to-newbies. As I'm also working towards a reloadable nsswitch.conf, I've classified each object as to whether it could be reloaded or not, and left in my ptr-to-* comments despite them obviously being wrong-syntax. I would greatly appreciate if anyone who understands nsswitch.conf could review my comments and let me know if my understanding of the code/objects is correct or not. Thanks! diff --git a/nss/nsswitch.h b/nss/nsswitch.h index 475e007e33..4e0dad5b0c 100644 --- a/nss/nsswitch.h +++ b/nss/nsswitch.h @@ -36,6 +36,7 @@ typedef enum NSS_ACTION_MERGE } lookup_actions; +/* Objects which could be persistent once loaded. */ typedef struct service_library { @@ -43,7 +44,9 @@ typedef struct service_library const char *name; /* Pointer to the loaded shared library. */ void *lib_handle; - /* And the link to the next entry. */ + /* And the link to the next entry, set by nss_new_service. This + link is used to free resources, and is not related to the order + of handlers for each service (that is NEXT in service_user). */ struct service_library *next; } service_library; @@ -53,20 +56,26 @@ typedef struct service_library is the first member. */ typedef struct { - const char *fct_name; - void *fct_ptr; + /* This is the API name, like `gethostbyname_r'. */ + const char *fct_name; /* ptr-to-malloc'd */ + /* This is the DLL function, like _nss_dns_gethostbyname_r(). */ + void *fct_ptr; /* ptr-to-persistent */ } known_function; +/* Objects which may be unloaded at runtime and/or replaced. */ typedef struct service_user { - /* And the link to the next entry. */ - struct service_user *next; + /* And the link to the next entry. In a line like `a : b c d' this + is the b->c->d link. */ + struct service_user *next; /* ptr-to-unloadable */ /* Action according to result. */ lookup_actions actions[5]; /* Link to the underlying library object. */ - service_library *library; - /* Collection of known functions. */ + service_library *library; /* ptr-to-persistent */ + /* Collection of known functions, mapping (for example) `foo' to + _nss_dns_foo(). Only contains mappings for this service and this + dll, so at least one and at most a few mappings. */ void *known; /* Name of the service (`files', `dns', `nis', ...). */ char name[0]; @@ -78,11 +87,12 @@ typedef struct service_user typedef struct name_database_entry { - /* And the link to the next entry. */ - struct name_database_entry *next; - /* List of service to be used. */ - service_user *service; - /* Name of the database. */ + /* And the link to the next entry. In a typical nsswitch.conf, this + is the passwd->group->hosts link. */ + struct name_database_entry *next; /* ptr-to-unloadable */ + /* List of services to be used. */ + service_user *service; /* ptr-to-unloadable */ + /* Name of the database (`passwd', `hosts', etc). */ char name[0]; } name_database_entry; @@ -90,12 +100,14 @@ typedef struct name_database_entry typedef struct name_database { /* List of all known databases. */ - name_database_entry *entry; + name_database_entry *entry; /* ptr-to-unloadable */ /* List of libraries with service implementation. */ - service_library *library; + service_library *library; /* ptr-to-persistent */ } name_database; +/* The rest of this header is not-data. */ + #ifdef USE_NSCD /* Indices into DATABASES in nsswitch.c and __NSS_DATABASE_CUSTOM. */ enum