Determine the host name associated with a channel.
const char *mtaChannelToHost(char **host, size_t *host_len, int item_code, ...); |
Arguments |
Description |
---|---|
host |
A pointer to receive the host name. The host name will be NULL terminated. NULL can be passed for this call argument. |
host_len |
An optional pointer to a size_t to receive the length in bytes of the returned host name. This length does not include the NULL terminator that terminates the host name. A value of NULL can be passed for this call argument. |
item_code |
An optional list of item codes. The list must be terminated with an integer argument with value 0. |
This routine is used to determine the host name associated with a particular channel.
The channel name can be specified in one of three ways:
Implicitly specified. For this case, no item codes other than the terminating 0 are specified and the channel name is the one for the running program. The channel name is set using the PMDF_CHANNEL environment variable.
Explicitly specified with the MTA_CHANNEL item code.
Set using the MTA_DQ_CONTEXT item code, which is taken to be the channel name associated with a specified dequeue context.
In all cases, the official host name of the selected channel is the host name that is returned. The official host name for a channel is the one that appears on the second line of the channel definition in the MTA configuration file, imta.conf.
The following table lists the item codes and any associated arguments:
Item Codes |
Additional Arguments |
Description |
---|---|---|
MTA_CHANNEL |
const char *channel size_t channel_len |
Explicitly specify a channel name for the official host name. This item code must be followed by the two additional call arguments, specifying:
|
MTA_DQ_CONTEXT |
mta_dq_t *dq_ctx |
Use the channel associated with the specified dequeue context. This item code must be followed by one additional call argument: a pointer to a dequeue context generated by mtaDequeueStart(). |
MTA_ITEM_LIST |
mta_item_list_t *item_list |
Specify a pointer to an item list array that is terminated with a final array entry that has an item code value of 0. For further information on item lists, see Item Codes and Item Lists. |
When none of the above item codes are specified, the channel name is taken from the runtime environment, using PMDF_CHANNEL environment variable.
On successful completion, the host name is stored in the buffer pointed at by the host argument, and the value of the host argument is returned.
In the event of an error, mtaChannelToHost() will return NULL, but will set mta_errno. The following table lists the error status codes for this routine.
printf("Host name: %s\n", mtaChannelToHost(NULL, NULL, MTA_CHANNEL, "tcp_local", 0, 0)); |