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" "access mail aliases database"
   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 .BI "void setaliasent(void);"
  14 .sp
  15 .BI "void endaliasent(void);"
  16 .sp
  17 .BI "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. (To find out
  31 which databases are supported, try  getent \-\-help .)
  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 .nf
  75
  76 struct aliasent {
  77     char    *alias_name;              /* alias name */
  78     size_t   alias_members_len;
  79     char   **alias_members;          /* alias name list */
  80     int      alias_local;
  81 };
  82 .fi
  83 .SH FILES
  84 The default alias database is the file
  85 .IR /etc/aliases .
  86 This can be changed in the
  87 .I /etc/nsswitch.conf
  88 file.
  89 .SH "RETURN VALUE"
  90 The functions
  91 .BR getaliasent_r ()
  92 and
  93 .BR getaliasbyname_r ()
  94 return a non-zero value on error.
  95 .SH EXAMPLE
  96 The following example compiles with
  97 .IR "gcc example.c \-o example" .
  98 It will dump all names in the alias database.
  99 .sp
 100 .nf
 101 #include <aliases.h>
 102 #include <stdio.h>
 103 #include <stdlib.h>
 104 #include <errno.h>
 105
 106 int
 107 main(void)
 108 {
 109     struct aliasent *al;
 110     setaliasent();
 111     for (;;) {
 112         al = getaliasent();
 113         if (al == NULL)
 114             break;
 115         printf("Name: %s\\n", al->alias_name);
 116     }
 117     if (errno) {
 118         perror("reading alias");
 119         exit(EXIT_FAILURE);
 120     }
 121     endaliasent();
 122     exit(EXIT_SUCCESS);
 123 }
 124 .fi
 125 .SH "CONFORMING TO"
 126 These routines are glibc-specific.
 127 The NeXT has similar routines
 128 .RS
 129 .nf
 130 #include <aliasdb.h>
 131 void alias_setent(void);
 132 void alias_endent(void);
 133 alias_ent *alias_getent(void);
 134 alias_ent *alias_getbyname(char *name);
 135 .fi
 136 .RE
 137 .SH "SEE ALSO"
 138 .BR getgrent (3),
 139 .BR getpwent (3),
 140 .BR getspent (3),
 141 .BR aliases (5)
 142 .\"
 143 .\" /etc/sendmail/aliases
 144 .\" Yellow Pages
 145 .\" newaliases, postalias