| .\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" Distributed under GPL |
| .\" %%%LICENSE_END |
| .\" |
| .\" Polished a bit, added a little, aeb |
| .\" |
| .TH SETALIASENT 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| setaliasent, endaliasent, getaliasent, getaliasent_r, |
| getaliasbyname, getaliasbyname_r \- read an alias entry |
| .SH SYNOPSIS |
| .B #include <aliases.h> |
| .PP |
| .B "void setaliasent(void);" |
| .PP |
| .B "void endaliasent(void);" |
| .PP |
| .B "struct aliasent *getaliasent(void);" |
| .PP |
| .BI "int getaliasent_r(struct aliasent *" result "," |
| .br |
| .BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); |
| .PP |
| .BI "struct aliasent *getaliasbyname(const char *" name ); |
| .PP |
| .BI "int getaliasbyname_r(const char *" name ", struct aliasent *" result , |
| .br |
| .BI " char *" buffer ", size_t " buflen ", struct aliasent **" res ); |
| .SH DESCRIPTION |
| One of the databases available with the Name Service Switch (NSS) |
| is the aliases database, that contains mail aliases. |
| (To find out which databases are supported, try |
| .IR "getent \-\-help" .) |
| Six functions are provided to access the aliases database. |
| .PP |
| The |
| .BR getaliasent () |
| function returns a pointer to a structure containing |
| the group information from the aliases database. |
| The first time it is called it returns the first entry; |
| thereafter, it returns successive entries. |
| .PP |
| The |
| .BR setaliasent () |
| function rewinds the file pointer to the beginning of the |
| aliases database. |
| .PP |
| The |
| .BR endaliasent () |
| function closes the aliases database. |
| .PP |
| .BR getaliasent_r () |
| is the reentrant version of the previous function. |
| The requested structure |
| is stored via the first argument but the programmer needs to fill the other |
| arguments also. |
| Not providing enough space causes the function to fail. |
| .PP |
| The function |
| .BR getaliasbyname () |
| takes the name argument and searches the aliases database. |
| The entry is returned as a pointer to a |
| .IR "struct aliasent" . |
| .PP |
| .BR getaliasbyname_r () |
| is the reentrant version of the previous function. |
| The requested structure |
| is stored via the second argument but the programmer needs to fill the other |
| arguments also. |
| Not providing enough space causes the function to fail. |
| .PP |
| The |
| .I "struct aliasent" |
| is defined in |
| .IR <aliases.h> : |
| .PP |
| .in +4n |
| .EX |
| struct aliasent { |
| char *alias_name; /* alias name */ |
| size_t alias_members_len; |
| char **alias_members; /* alias name list */ |
| int alias_local; |
| }; |
| .EE |
| .in |
| .SH RETURN VALUE |
| The functions |
| .BR getaliasent_r () |
| and |
| .BR getaliasbyname_r () |
| return a nonzero value on error. |
| .SH FILES |
| The default alias database is the file |
| .IR /etc/aliases . |
| This can be changed in the |
| .I /etc/nsswitch.conf |
| file. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .TS |
| allbox; |
| lbw19 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR setaliasent (), |
| .BR endaliasent (), |
| .BR getaliasent_r (), |
| .BR getaliasbyname_r () |
| T} Thread safety MT-Safe locale |
| T{ |
| .BR getaliasent (), |
| .BR getaliasbyname () |
| T} Thread safety MT-Unsafe |
| .TE |
| .ad |
| .SH CONFORMING TO |
| These routines are glibc-specific. |
| The NeXT system has similar routines: |
| .PP |
| .in +4n |
| .EX |
| #include <aliasdb.h> |
| |
| void alias_setent(void); |
| void alias_endent(void); |
| alias_ent *alias_getent(void); |
| alias_ent *alias_getbyname(char *name); |
| .EE |
| .in |
| .SH EXAMPLE |
| The following example compiles with |
| .IR "gcc example.c \-o example" . |
| It will dump all names in the alias database. |
| .PP |
| .EX |
| #include <aliases.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <errno.h> |
| |
| int |
| main(void) |
| { |
| struct aliasent *al; |
| setaliasent(); |
| for (;;) { |
| al = getaliasent(); |
| if (al == NULL) |
| break; |
| printf("Name: %s\en", al\->alias_name); |
| } |
| if (errno) { |
| perror("reading alias"); |
| exit(EXIT_FAILURE); |
| } |
| endaliasent(); |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR getgrent (3), |
| .BR getpwent (3), |
| .BR getspent (3), |
| .BR aliases (5) |
| .\" |
| .\" /etc/sendmail/aliases |
| .\" Yellow Pages |
| .\" newaliases, postalias |