Mercurial > hg > nginx-site
comparison xml/en/docs/dev/development_guide.xml @ 1928:2c14a16c61eb
Added modules section to development guide.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Fri, 10 Mar 2017 16:33:09 +0300 |
parents | de5251816480 |
children | 7f290929b32d |
comparison
equal
deleted
inserted
replaced
1927:75d2478260f4 | 1928:2c14a16c61eb |
---|---|
2726 process, whose pid is read from nginx pid file. | 2726 process, whose pid is read from nginx pid file. |
2727 </para> | 2727 </para> |
2728 | 2728 |
2729 </section> | 2729 </section> |
2730 | 2730 |
2731 <section name="Modules" id="Modules"> | |
2732 | |
2733 <section name="Adding new modules" id="adding_new_modules"> | |
2734 <para> | |
2735 The standalone nginx module resides in a separate directory that contains | |
2736 at least two files: | |
2737 <literal>config</literal> and a file with the module source. | |
2738 The first file contains all information needed for nginx to integrate | |
2739 the module, for example: | |
2740 <programlisting> | |
2741 ngx_module_type=CORE | |
2742 ngx_module_name=ngx_foo_module | |
2743 ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c" | |
2744 | |
2745 . auto/module | |
2746 | |
2747 ngx_addon_name=$ngx_module_name | |
2748 </programlisting> | |
2749 The file is a POSIX shell script and it can set (or access) the | |
2750 following variables: | |
2751 <list type="bullet"> | |
2752 | |
2753 <listitem> | |
2754 <literal>ngx_module_type</literal> - the type of module to build. | |
2755 Possible options are <literal>CORE</literal>, <literal>HTTP</literal>, | |
2756 <literal>HTTP_FILTER</literal>, <literal>HTTP_INIT_FILTER</literal>, | |
2757 <literal>HTTP_AUX_FILTER</literal>, <literal>MAIL</literal>, | |
2758 <literal>STREAM</literal>, or <literal>MISC</literal> | |
2759 </listitem> | |
2760 | |
2761 <listitem> | |
2762 <literal>ngx_module_name</literal> - the name of the module. | |
2763 A whitespace separated values list is accepted and may be used to build | |
2764 multiple modules from a single set of source files. | |
2765 The first name indicates the name of the output binary for a dynamic module. | |
2766 The names in this list should match the names used in the module. | |
2767 </listitem> | |
2768 | |
2769 <listitem> | |
2770 <literal>ngx_addon_name</literal> - supplies the name of the module in the | |
2771 console output text of the configure script. | |
2772 </listitem> | |
2773 | |
2774 <listitem> | |
2775 <literal>ngx_module_srcs</literal> - a whitespace separated list of source | |
2776 files used to compile the module. | |
2777 The $ngx_addon_dir variable can be used as a placeholder for the path of the | |
2778 module source. | |
2779 </listitem> | |
2780 | |
2781 <listitem> | |
2782 <literal>ngx_module_incs</literal> - include paths required to build the module | |
2783 </listitem> | |
2784 | |
2785 <listitem> | |
2786 <literal>ngx_module_deps</literal> - a list of module's header files. | |
2787 </listitem> | |
2788 | |
2789 <listitem> | |
2790 <literal>ngx_module_libs</literal> - a list of libraries to link with the | |
2791 module. | |
2792 For example, libpthread would be linked using | |
2793 <literal>ngx_module_libs=-lpthread</literal>. | |
2794 The following macros can be used to link against the same libraries as | |
2795 nginx: | |
2796 <literal>LIBXSLT</literal>, <literal>LIBGD</literal>, <literal>GEOIP</literal>, | |
2797 <literal>PCRE</literal>, <literal>OPENSSL</literal>, <literal>MD5</literal>, | |
2798 <literal>SHA1</literal>, <literal>ZLIB</literal>, and <literal>PERL</literal> | |
2799 </listitem> | |
2800 | |
2801 <listitem> | |
2802 <literal>ngx_module_link</literal> - set by the build system to | |
2803 <literal>DYNAMIC</literal> for a dynamic module or <literal>ADDON</literal> | |
2804 for a static module and used to perform different actions depending on | |
2805 linking type. | |
2806 </listitem> | |
2807 | |
2808 <listitem> | |
2809 <literal>ngx_module_order</literal> - sets the load order for the module which | |
2810 is useful for <literal>HTTP_FILTER</literal> and | |
2811 <literal>HTTP_AUX_FILTER</literal> module types. | |
2812 The order is stored in a reverse list. | |
2813 | |
2814 <para> | |
2815 The <literal>ngx_http_copy_filter_module</literal> is near the bottom of the | |
2816 list so is one of the first to be executed. | |
2817 This reads the data for other filters. | |
2818 Near the top of the list is <literal>ngx_http_write_filter_module</literal> | |
2819 which writes the data out and is one of the last to be executed. | |
2820 </para> | |
2821 | |
2822 <para> | |
2823 The format for this option is typically the current module’s name followed by | |
2824 a whitespace separated list of modules to insert before, and therefore execute | |
2825 after. | |
2826 The module will be inserted before the last module in the list that is found | |
2827 to be currently loaded. | |
2828 </para> | |
2829 | |
2830 <para> | |
2831 By default for filter modules this is set to | |
2832 “<literal>ngx_http_copy_filter</literal>” which will insert the module before | |
2833 the copy filter in the list and therefore will execute after the copy filter. | |
2834 For other module types the default is empty. | |
2835 </para> | |
2836 | |
2837 </listitem> | |
2838 | |
2839 </list> | |
2840 | |
2841 A module can be added to nginx by means of the configure script using | |
2842 <literal>--add-module=/path/to/module</literal> for static compilation and | |
2843 <literal>--add-dynamic-module=/path/to/module</literal> for dynamic compilation. | |
2844 </para> | |
2845 | |
2846 </section> | |
2847 | |
2848 | |
2849 <section name="Core modules" id="core_modules"> | |
2850 | |
2851 <para> | |
2852 Modules are building blocks of nginx, and most of its functionality is | |
2853 implemented as modules. | |
2854 The module source file must contain a global variable of | |
2855 <literal>ngx_module_t</literal> type which is defined as follows: | |
2856 <programlisting> | |
2857 struct ngx_module_s { | |
2858 | |
2859 /* private part is omitted */ | |
2860 | |
2861 void *ctx; | |
2862 ngx_command_t *commands; | |
2863 ngx_uint_t type; | |
2864 | |
2865 ngx_int_t (*init_master)(ngx_log_t *log); | |
2866 | |
2867 ngx_int_t (*init_module)(ngx_cycle_t *cycle); | |
2868 | |
2869 ngx_int_t (*init_process)(ngx_cycle_t *cycle); | |
2870 ngx_int_t (*init_thread)(ngx_cycle_t *cycle); | |
2871 void (*exit_thread)(ngx_cycle_t *cycle); | |
2872 void (*exit_process)(ngx_cycle_t *cycle); | |
2873 | |
2874 void (*exit_master)(ngx_cycle_t *cycle); | |
2875 | |
2876 /* stubs for future extensions are omitted */ | |
2877 }; | |
2878 </programlisting> | |
2879 The omitted private part includes module version, signature and is filled | |
2880 using the predefined macro <literal>NGX_MODULE_V1</literal>. | |
2881 </para> | |
2882 | |
2883 <para> | |
2884 Each module keeps its private data in the <literal>ctx</literal> field, | |
2885 recognizes specific configuration directives, specified in the | |
2886 <literal>commands</literal> array, and may be invoked at certain stages of | |
2887 nginx lifecycle. | |
2888 The module lifecycle consists of the following events: | |
2889 | |
2890 <list type="bullet"> | |
2891 | |
2892 <listitem> | |
2893 Configuration directive handlers are called as they appear | |
2894 in configuration files in the context of the master process | |
2895 </listitem> | |
2896 | |
2897 <listitem> | |
2898 The <literal>init_module</literal> handler is called in the context of | |
2899 the master process after the configuration is parsed successfully | |
2900 </listitem> | |
2901 | |
2902 <listitem> | |
2903 The master process creates worker process(es) and | |
2904 <literal>init_process</literal> handler is called in each of them | |
2905 </listitem> | |
2906 | |
2907 <listitem> | |
2908 When a worker process receives the shutdown command from master, it invokes | |
2909 the <literal>exit_process</literal> handler | |
2910 </listitem> | |
2911 | |
2912 <listitem> | |
2913 The master process calls the <literal>exit_master</literal> handler before | |
2914 exiting. | |
2915 </listitem> | |
2916 | |
2917 </list> | |
2918 | |
2919 <note> | |
2920 <literal>init_module</literal> handler may be called multiple times | |
2921 in the master process if the configuration reload is requested. | |
2922 </note> | |
2923 | |
2924 The <literal>init_master</literal>, <literal>init_thread</literal> and | |
2925 <literal>exit_thread</literal> handlers are not implemented at the moment; | |
2926 Threads in nginx are only used as supplementary I/O facility with its own | |
2927 API and <literal>init_master</literal> handler looks unnecessary. | |
2928 </para> | |
2929 | |
2930 <para> | |
2931 The module <literal>type</literal> defines what exactly is stored in the | |
2932 <literal>ctx</literal> field. | |
2933 There are several types of modules: | |
2934 <list type="bullet"> | |
2935 <listitem><literal>NGX_CORE_MODULE</literal></listitem> | |
2936 <listitem><literal>NGX_EVENT_MODULE</literal></listitem> | |
2937 <listitem><literal>NGX_HTTP_MODULE</literal></listitem> | |
2938 <listitem><literal>NGX_MAIL_MODULE</literal></listitem> | |
2939 <listitem><literal>NGX_STREAM_MODULE</literal></listitem> | |
2940 </list> | |
2941 The <literal>NGX_CORE_MODULE</literal> is the most basic and thus the most | |
2942 generic and most low-level type of module. Other module types are implemented | |
2943 on top of it and provide more convenient way to deal with corresponding | |
2944 problem domains, like handling events or http requests. | |
2945 </para> | |
2946 | |
2947 <para> | |
2948 The examples of core modules are <literal>ngx_core_module</literal>, | |
2949 <literal>ngx_errlog_module</literal>, <literal>ngx_regex_module</literal>, | |
2950 <literal>ngx_thread_pool_module</literal>, | |
2951 <literal>ngx_openssl_module</literal> | |
2952 modules and, of course, http, stream, mail and event modules itself. | |
2953 The context of a core module is defined as: | |
2954 <programlisting> | |
2955 typedef struct { | |
2956 ngx_str_t name; | |
2957 void *(*create_conf)(ngx_cycle_t *cycle); | |
2958 char *(*init_conf)(ngx_cycle_t *cycle, void *conf); | |
2959 } ngx_core_module_t; | |
2960 </programlisting> | |
2961 where the <literal>name</literal> is a string with a module name for | |
2962 convenience, <literal>create_conf</literal> and <literal>init_conf</literal> | |
2963 are pointers to functions that create and initialize module configuration | |
2964 correspondingly. | |
2965 For core modules, nginx will call <literal>create_conf</literal> before parsing | |
2966 a new configuration and <literal>init_conf</literal> after all configuration | |
2967 was parsed successfully. | |
2968 The typical <literal>create_conf</literal> function allocates memory for the | |
2969 configuration and sets default values. | |
2970 The <literal>init_conf</literal> deals with known configuration and thus may | |
2971 perform sanity checks and complete initialization. | |
2972 </para> | |
2973 | |
2974 <para> | |
2975 For example, the simplistic <literal>ngx_foo_module</literal> can look like | |
2976 this: | |
2977 <programlisting> | |
2978 /* | |
2979 * Copyright (C) Author. | |
2980 */ | |
2981 | |
2982 | |
2983 #include <ngx_config.h> | |
2984 #include <ngx_core.h> | |
2985 | |
2986 | |
2987 typedef struct { | |
2988 ngx_flag_t enable; | |
2989 } ngx_foo_conf_t; | |
2990 | |
2991 | |
2992 static void *ngx_foo_create_conf(ngx_cycle_t *cycle); | |
2993 static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf); | |
2994 | |
2995 static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data); | |
2996 static ngx_conf_post_t ngx_foo_enable_post = { ngx_foo_enable }; | |
2997 | |
2998 | |
2999 static ngx_command_t ngx_foo_commands[] = { | |
3000 | |
3001 { ngx_string("foo_enabled"), | |
3002 NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG, | |
3003 ngx_conf_set_flag_slot, | |
3004 0, | |
3005 offsetof(ngx_foo_conf_t, enable), | |
3006 &ngx_foo_enable_post }, | |
3007 | |
3008 ngx_null_command | |
3009 }; | |
3010 | |
3011 | |
3012 static ngx_core_module_t ngx_foo_module_ctx = { | |
3013 ngx_string("foo"), | |
3014 ngx_foo_create_conf, | |
3015 ngx_foo_init_conf | |
3016 }; | |
3017 | |
3018 | |
3019 ngx_module_t ngx_foo_module = { | |
3020 NGX_MODULE_V1, | |
3021 &ngx_foo_module_ctx, /* module context */ | |
3022 ngx_foo_commands, /* module directives */ | |
3023 NGX_CORE_MODULE, /* module type */ | |
3024 NULL, /* init master */ | |
3025 NULL, /* init module */ | |
3026 NULL, /* init process */ | |
3027 NULL, /* init thread */ | |
3028 NULL, /* exit thread */ | |
3029 NULL, /* exit process */ | |
3030 NULL, /* exit master */ | |
3031 NGX_MODULE_V1_PADDING | |
3032 }; | |
3033 | |
3034 | |
3035 static void * | |
3036 ngx_foo_create_conf(ngx_cycle_t *cycle) | |
3037 { | |
3038 ngx_foo_conf_t *fcf; | |
3039 | |
3040 fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t)); | |
3041 if (fcf == NULL) { | |
3042 return NULL; | |
3043 } | |
3044 | |
3045 fcf->enable = NGX_CONF_UNSET; | |
3046 | |
3047 return fcf; | |
3048 } | |
3049 | |
3050 | |
3051 static char * | |
3052 ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf) | |
3053 { | |
3054 ngx_foo_conf_t *fcf = conf; | |
3055 | |
3056 ngx_conf_init_value(fcf->enable, 0); | |
3057 | |
3058 return NGX_CONF_OK; | |
3059 } | |
3060 | |
3061 | |
3062 static char * | |
3063 ngx_foo_enable(ngx_conf_t *cf, void *post, void *data) | |
3064 { | |
3065 ngx_flag_t *fp = data; | |
3066 | |
3067 if (*fp == 0) { | |
3068 return NGX_CONF_OK; | |
3069 } | |
3070 | |
3071 ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled"); | |
3072 | |
3073 return NGX_CONF_OK; | |
3074 } | |
3075 </programlisting> | |
3076 </para> | |
3077 | |
3078 </section> | |
3079 | |
3080 | |
3081 <section name="Configuration directives" id="config_directives"> | |
3082 | |
3083 <para> | |
3084 The <literal>ngx_command_t</literal> describes single configuration directive. | |
3085 Each module, supporting configuration, provides an array of such specifications | |
3086 that describe how to process arguments and what handlers to call: | |
3087 <programlisting> | |
3088 struct ngx_command_s { | |
3089 ngx_str_t name; | |
3090 ngx_uint_t type; | |
3091 char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); | |
3092 ngx_uint_t conf; | |
3093 ngx_uint_t offset; | |
3094 void *post; | |
3095 }; | |
3096 </programlisting> | |
3097 The array should be terminated by a special value | |
3098 “<literal>ngx_null_command</literal>”. | |
3099 The <literal>name</literal> is the literal name of a directive, as it appears | |
3100 in configuration file, for example “<literal>worker_processes</literal>” or | |
3101 “<literal>listen</literal>”. | |
3102 The <literal>type</literal> is a bitfield that controls number of arguments, | |
3103 command type and other properties using corresponding flags. | |
3104 Arguments flags: | |
3105 | |
3106 <list type="bullet"> | |
3107 | |
3108 <listitem> | |
3109 <literal>NGX_CONF_NOARGS</literal> - directive without arguments | |
3110 </listitem> | |
3111 | |
3112 <listitem><literal>NGX_CONF_1MORE</literal> - one required argument</listitem> | |
3113 | |
3114 <listitem><literal>NGX_CONF_2MORE</literal> - two required arguments</listitem> | |
3115 | |
3116 <listitem> | |
3117 <literal>NGX_CONF_TAKE1..7</literal> - exactly 1..7 arguments | |
3118 </listitem> | |
3119 | |
3120 <listitem> | |
3121 <literal>NGX_CONF_TAKE12, 13, 23, 123, 1234</literal> - one or two arguments, | |
3122 or other combinations | |
3123 </listitem> | |
3124 | |
3125 </list> | |
3126 | |
3127 Directive types: | |
3128 | |
3129 <list type="bullet"> | |
3130 | |
3131 <listitem> | |
3132 <literal>NGX_CONF_BLOCK</literal> - the directive is a block, i.e. it may | |
3133 contain other directives in curly braces, or even implement its own parser | |
3134 to handle contents inside. | |
3135 </listitem> | |
3136 | |
3137 <listitem> | |
3138 <literal>NGX_CONF_FLAG</literal> - the directive value is a flag, a boolean | |
3139 value represented by “<literal>on</literal>” or “<literal>off</literal>” | |
3140 strings. | |
3141 </listitem> | |
3142 </list> | |
3143 | |
3144 Context of a directive defines where in the configuration it may appear | |
3145 and how to access module context to store corresponding values: | |
3146 <list type="bullet"> | |
3147 | |
3148 <listitem> | |
3149 <literal>NGX_MAIN_CONF</literal> - top level configuration | |
3150 </listitem> | |
3151 | |
3152 <listitem> | |
3153 <literal>NGX_HTTP_MAIN_CONF</literal> - in the http block | |
3154 </listitem> | |
3155 | |
3156 <listitem> | |
3157 <literal>NGX_HTTP_SRV_CONF</literal> - in the http server block | |
3158 </listitem> | |
3159 | |
3160 <listitem> | |
3161 <literal>NGX_HTTP_LOC_CONF</literal> - in the http location | |
3162 </listitem> | |
3163 | |
3164 <listitem> | |
3165 <literal>NGX_HTTP_UPS_CONF</literal> - in the http upstream block | |
3166 </listitem> | |
3167 | |
3168 <listitem> | |
3169 <literal>NGX_HTTP_SIF_CONF</literal> - in the http server “if” | |
3170 </listitem> | |
3171 | |
3172 <listitem> | |
3173 <literal>NGX_HTTP_LIF_CONF</literal> - in the http location “if” | |
3174 </listitem> | |
3175 | |
3176 <listitem> | |
3177 <literal>NGX_HTTP_LMT_CONF</literal> - in the http “limit_except” | |
3178 </listitem> | |
3179 | |
3180 <listitem> | |
3181 <literal>NGX_STREAM_MAIN_CONF</literal> - in the stream block | |
3182 </listitem> | |
3183 | |
3184 <listitem> | |
3185 <literal>NGX_STREAM_SRV_CONF</literal> - in the stream server block | |
3186 </listitem> | |
3187 | |
3188 <listitem> | |
3189 <literal>NGX_STREAM_UPS_CONF</literal> - in the stream upstream block | |
3190 </listitem> | |
3191 | |
3192 <listitem> | |
3193 <literal>NGX_MAIL_MAIN_CONF</literal> - in the the mail block | |
3194 </listitem> | |
3195 | |
3196 <listitem> | |
3197 <literal>NGX_MAIL_SRV_CONF</literal> - in the mail server block | |
3198 </listitem> | |
3199 | |
3200 <listitem> | |
3201 <literal>NGX_EVENT_CONF</literal> - in the event block | |
3202 </listitem> | |
3203 | |
3204 <listitem> | |
3205 <literal>NGX_DIRECT_CONF</literal> - used by modules that don't | |
3206 create a hierarchy of contexts and store module configuration directly in ctx | |
3207 </listitem> | |
3208 </list> | |
3209 The configuration parser uses this flags to throw an error in case of | |
3210 a misplaced directive and calls directive handlers supplied with a proper | |
3211 configuration pointer, so that same directives in different locations could | |
3212 store their values in distinct places. | |
3213 </para> | |
3214 | |
3215 <para> | |
3216 The <literal>set</literal> field defines a handler that processes a directive | |
3217 and stores parsed values into corresponding configuration. | |
3218 Nginx offers a convenient set of functions that perform common conversions: | |
3219 | |
3220 <list type="bullet"> | |
3221 | |
3222 <listitem> | |
3223 <literal>ngx_conf_set_flag_slot</literal> - converts literal | |
3224 “<literal>on</literal>” or “<literal>off</literal>” strings into | |
3225 <literal>ngx_flag_t</literal> type with values 1 or 0 | |
3226 </listitem> | |
3227 | |
3228 <listitem> | |
3229 <literal>ngx_conf_set_str_slot</literal> - stores string as a value of the | |
3230 <literal>ngx_str_t</literal> type | |
3231 </listitem> | |
3232 | |
3233 <listitem> | |
3234 <literal>ngx_conf_set_str_array_slot</literal> - appends | |
3235 <literal>ngx_array_t</literal> of <literal>ngx_str_t</literal> with a new value. | |
3236 The array is created if not yet exists | |
3237 </listitem> | |
3238 | |
3239 <listitem> | |
3240 <literal>ngx_conf_set_keyval_slot</literal> - appends | |
3241 <literal>ngx_array_t</literal> of <literal>ngx_keyval_t</literal> with | |
3242 a new value, where key is the first string and value is second. | |
3243 The array is created if not yet exists | |
3244 </listitem> | |
3245 | |
3246 <listitem> | |
3247 <literal>ngx_conf_set_num_slot</literal> - converts directive argument | |
3248 to a <literal>ngx_int_t</literal> value | |
3249 </listitem> | |
3250 | |
3251 <listitem> | |
3252 <literal>ngx_conf_set_size_slot</literal> - converts | |
3253 <link doc="../syntax.xml">size</link> to <literal>size_t</literal> value | |
3254 in bytes | |
3255 </listitem> | |
3256 | |
3257 <listitem> | |
3258 <literal>ngx_conf_set_off_slot</literal> - converts | |
3259 <link doc="../syntax.xml">offset</link> to <literal>off_t</literal> value | |
3260 in bytes | |
3261 </listitem> | |
3262 | |
3263 <listitem> | |
3264 <literal>ngx_conf_set_msec_slot</literal> - converts | |
3265 <link doc="../syntax.xml">time</link> to <literal>ngx_msec_t</literal> value | |
3266 in milliseconds | |
3267 </listitem> | |
3268 | |
3269 <listitem> | |
3270 <literal>ngx_conf_set_sec_slot</literal> - converts | |
3271 <link doc="../syntax.xml">time</link> to <literal>time_t</literal> value | |
3272 in seconds | |
3273 </listitem> | |
3274 | |
3275 <listitem> | |
3276 <literal>ngx_conf_set_bufs_slot</literal> - converts two arguments | |
3277 into <literal>ngx_bufs_t</literal> that holds <literal>ngx_int_t</literal> | |
3278 number and <link doc="../syntax.xml">size</link> of buffers | |
3279 </listitem> | |
3280 | |
3281 <listitem> | |
3282 <literal>ngx_conf_set_enum_slot</literal> - converts argument | |
3283 into <literal>ngx_uint_t</literal> value. | |
3284 The null-terminated array of <literal>ngx_conf_enum_t</literal> passed in the | |
3285 <literal>post</literal> field defines acceptable strings and corresponding | |
3286 integer values | |
3287 </listitem> | |
3288 | |
3289 <listitem> | |
3290 <literal>ngx_conf_set_bitmask_slot</literal> - arguments are converted to | |
3291 <literal>ngx_uint_t</literal> value and OR'ed with the resulting value, | |
3292 forming a bitmask. | |
3293 The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in | |
3294 the <literal>post</literal> field defines acceptable strings and corresponding | |
3295 mask values | |
3296 </listitem> | |
3297 | |
3298 <listitem> | |
3299 <literal>set_path_slot</literal> - converts arguments to | |
3300 <literal>ngx_path_t</literal> type and performs all required initializations. | |
3301 See the | |
3302 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">proxy_temp_path</link> | |
3303 directive description for details | |
3304 </listitem> | |
3305 | |
3306 <listitem> | |
3307 <literal>set_access_slot</literal> - converts arguments to file permissions | |
3308 mask. | |
3309 See the | |
3310 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">proxy_store_access</link> | |
3311 directive description for details | |
3312 </listitem> | |
3313 | |
3314 </list> | |
3315 | |
3316 </para> | |
3317 | |
3318 <para> | |
3319 The <literal>conf</literal> field defines which context is used to store | |
3320 the value of the directive, or zero if contexts are not used. | |
3321 Only simple core modules use configuration without context and set | |
3322 <literal>NGX_DIRECT_CONF</literal> flag. | |
3323 In real life, such modules like http or stream require more sophisticated | |
3324 configuration that can be applied per-server or per-location, or even more | |
3325 precisely, in the context of the “<literal>if</literal>” directive or | |
3326 some limit. | |
3327 In this modules, configuration structure is more complex. | |
3328 Please refer to corresponding modules description to understand how | |
3329 they manage their configuration. | |
3330 | |
3331 <list type="bullet"> | |
3332 <listitem> | |
3333 <literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> - http block configuration | |
3334 </listitem> | |
3335 | |
3336 <listitem> | |
3337 <literal>NGX_HTTP_SRV_CONF_OFFSET</literal> - http server configuration | |
3338 </listitem> | |
3339 | |
3340 <listitem> | |
3341 <literal>NGX_HTTP_LOC_CONF_OFFSET</literal> - http location configuration | |
3342 </listitem> | |
3343 | |
3344 <listitem> | |
3345 <literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> - stream block configuration | |
3346 </listitem> | |
3347 | |
3348 <listitem> | |
3349 <literal>NGX_STREAM_SRV_CONF_OFFSET</literal> - stream server configuration | |
3350 </listitem> | |
3351 | |
3352 <listitem> | |
3353 <literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> - mail block configuration | |
3354 </listitem> | |
3355 | |
3356 <listitem> | |
3357 <literal>NGX_MAIL_SRV_CONF_OFFSET</literal> - mail server configuration | |
3358 </listitem> | |
3359 | |
3360 </list> | |
3361 | |
3362 </para> | |
3363 | |
3364 <para> | |
3365 The <literal>offset</literal> defines an offset of a field in a module | |
3366 configuration structure that holds values of this particular directive. | |
3367 The typical use is to employ <literal>offsetof()</literal> macro. | |
3368 </para> | |
3369 | |
3370 <para> | |
3371 The <literal>post</literal> is a twofold field: it may be used to define | |
3372 a handler to be called after main handler completed or to pass additional | |
3373 data to the main handler. | |
3374 In the first case, <literal>ngx_conf_post_t</literal> structure needs to | |
3375 be initialized with a pointer to handler, for example: | |
3376 <programlisting> | |
3377 static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data); | |
3378 static ngx_conf_post_t ngx_foo_post = { ngx_do_foo }; | |
3379 </programlisting> | |
3380 The <literal>post</literal> argument is the <literal>ngx_conf_post_t</literal> | |
3381 object itself, and the <literal>data</literal> is a pointer to value, | |
3382 converted from arguments by the main handler with the appropriate type. | |
3383 </para> | |
3384 | |
3385 </section> | |
3386 | |
3387 </section> | |
3388 | |
3389 | |
2731 </article> | 3390 </article> |