man3/setaliasent.3

   1 .\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" Distributed under GPL
   3 .\"
   4 .\" Polished a bit, added a little, aeb
   5 .\"
   6 .TH SETALIASENT 3 2003-09-09 "GNU" "Linux Programmer's Manual"
   7 .SH NAME
   8 setaliasent, endaliasent, getaliasent, getaliasent_r,
   9 getaliasbyname, getaliasbyname_r \- read an alias entry
  10 .SH SYNOPSIS
  11 .B #include <aliases.h>
  12 .sp
  13 .B "void setaliasent(void);"
  14 .sp
  15 .B "void endaliasent(void);"
  16 .sp
  17 .B "struct aliasent *getaliasent(void);"
  18 .sp
  19 .BI "int getaliasent_r(struct aliasent *" result ","
  20 .br
  21 .BI "        char *" buffer ", size_t " buflen ", struct aliasent **" res );
  22 .sp
  23 .BI "struct aliasent *getaliasbyname(const char *" name );
  24 .sp
  25 .BI "int getaliasbyname_r(const char *" name ", struct aliasent *" result ,
  26 .br
  27 .BI "        char *" buffer ", size_t " buflen ", struct aliasent **" res );
  28 .SH DESCRIPTION
  29 One of the databases available with the Name Service Switch (NSS)
  30 is the aliases database, that contains mail aliases.
  31 (To find out which databases are supported, try  \fIgetent \-\-help\fP.)
  32 Six functions are provided to access the aliases database.
  33 .PP
  34 The
  35 .BR getaliasent ()
  36 function returns a pointer to a structure containing
  37 the group information from the aliases database.
  38 The first time it is called it returns the first entry;
  39 thereafter, it returns successive entries.
  40 .PP
  41 The
  42 .BR setaliasent ()
  43 function rewinds the file pointer to the beginning of the
  44 aliases database.
  45 .PP
  46 The
  47 .BR endaliasent ()
  48 function closes the aliases database.
  49 .PP
  50 .BR getaliasent_r ()
  51 is the reentrant version of the previous function.
  52 The requested structure
  53 is stored via the first argument but the programmer needs to fill the other
  54 arguments also.
  55 Not providing enough space causes the function to fail.
  56 .PP
  57 The function
  58 .BR getaliasbyname ()
  59 takes the name argument and searches the aliases database.
  60 The entry is returned as a pointer to a
  61 .IR "struct aliasent" .
  62 .PP
  63 .BR getaliasbyname_r ()
  64 is the reentrant version of the previous function.
  65 The requested structure
  66 is stored via the second argument but the programmer needs to fill the other
  67 arguments also.
  68 Not providing enough space causes the function to fail.
  69 .PP
  70 The
  71 .I "struct aliasent"
  72 is defined in
  73 .IR <aliases.h> :
  74 .in +4n
  75 .nf
  76
  77 struct aliasent {
  78     char    *alias_name;             /* alias name */
  79     size_t   alias_members_len;
  80     char   **alias_members;           /* alias name list */
  81     int      alias_local;
  82 };
  83 .fi
  84 .in
  85 .SH "RETURN VALUE"
  86 The functions
  87 .BR getaliasent_r ()
  88 and
  89 .BR getaliasbyname_r ()
  90 return a non-zero value on error.
  91 .SH FILES
  92 The default alias database is the file
  93 .IR /etc/aliases .
  94 This can be changed in the
  95 .I /etc/nsswitch.conf
  96 file.
  97 .SH "CONFORMING TO"
  98 These routines are glibc-specific.
  99 The NeXT has similar routines:
 100 .in +4n
 101 .nf
 102
 103 #include <aliasdb.h>
 104
 105 void alias_setent(void);
 106 void alias_endent(void);
 107 alias_ent *alias_getent(void);
 108 alias_ent *alias_getbyname(char *name);
 109 .fi
 110 .in
 111 .SH EXAMPLE
 112 The following example compiles with
 113 .IR "gcc example.c \-o example" .
 114 It will dump all names in the alias database.
 115 .sp
 116 .nf
 117 #include <aliases.h>
 118 #include <stdio.h>
 119 #include <stdlib.h>
 120 #include <errno.h>
 121
 122 int
 123 main(void)
 124 {
 125     struct aliasent *al;
 126     setaliasent();
 127     for (;;) {
 128         al = getaliasent();
 129         if (al == NULL)
 130             break;
 131         printf("Name: %s\\n", al\->alias_name);
 132     }
 133     if (errno) {
 134         perror("reading alias");
 135         exit(EXIT_FAILURE);
 136     }
 137     endaliasent();
 138     exit(EXIT_SUCCESS);
 139 }
 140 .fi
 141 .SH "SEE ALSO"
 142 .BR getgrent (3),
 143 .BR getpwent (3),
 144 .BR getspent (3),
 145 .BR aliases (5)
 146 .\"
 147 .\" /etc/sendmail/aliases
 148 .\" Yellow Pages
 149 .\" newaliases, postalias