1/* Declarations for file attribute munging features.
2
3   This program is free software; you can redistribute it and/or modify
4   it under the terms of the GNU General Public License as published by
5   the Free Software Foundation; either version 2, or (at your option)
6   any later version.
7
8   This program is distributed in the hope that it will be useful,
9   but WITHOUT ANY WARRANTY; without even the implied warranty of
10   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11   GNU General Public License for more details.  */
12
13#ifndef FILEATTR_H
14
15/* File containing per-file attributes.  The format of this file is in
16   cvs.texinfo but here is a quick summary.  The file contains a
17   series of entries:
18
19   ENT-TYPE FILENAME <tab> ATTRNAME = ATTRVAL
20     {; ATTRNAME = ATTRVAL} <linefeed>
21
22   ENT-TYPE is 'F' for a file.
23
24   ENT-TYPE is 'D', and FILENAME empty, for default attributes.
25
26   Other ENT-TYPE are reserved for future expansion.
27
28   Note that the order of the line is not significant; CVS is free to
29   rearrange them at its convenience.
30
31   FIXME: this implementation doesn't handle '\0' in any of the
32   fields.  We are encouraged to fix this (by cvs.texinfo).
33
34   By convention, ATTRNAME starting with '_' is for an attribute given
35   special meaning by CVS; other ATTRNAMEs are for user-defined attributes
36   (or will be, once we add commands to manipulate user-defined attributes).
37
38   Builtin attributes:
39
40   _watched: Present means the file is watched and should be checked out
41   read-only.
42
43   _watchers: Users with watches for this file.  Value is
44   WATCHER > TYPE { , WATCHER > TYPE }
45   where WATCHER is a username, and TYPE is edit,unedit,commit separated by
46   + (or nothing if none; there is no "none" or "all" keyword).
47
48   _editors: Users editing this file.  Value is
49   EDITOR > VAL { , EDITOR > VAL }
50   where EDITOR is a username, and VAL is TIME+HOSTNAME+PATHNAME, where
51   TIME is when the "cvs edit" command happened,
52   and HOSTNAME and PATHNAME are for the working directory.  */
53
54#define CVSREP_FILEATTR "CVS/fileattr"
55
56/* Prepare for a new directory with repository REPOS.  If REPOS is NULL,
57   then prepare for a "non-directory"; the caller can call fileattr_write
58   and fileattr_free, but must not call fileattr_get or fileattr_set.  */
59extern void fileattr_startdir PROTO ((const char *repos));
60
61/* Get the attribute ATTRNAME for file FILENAME.  The return value
62   points into memory managed by the fileattr_* routines, should not
63   be altered by the caller, and is only good until the next call to
64   fileattr_clear or fileattr_set.  It points to the value, terminated
65   by '\0' or ';'.  Return NULL if said file lacks said attribute.
66   If FILENAME is NULL, return default attributes (attributes for
67   files created in the future).  */
68extern char *fileattr_get PROTO ((const char *filename, const char *attrname));
69
70/* Like fileattr_get, but return a pointer to a newly malloc'd string
71   terminated by '\0' (or NULL if said file lacks said attribute).  */
72extern char *fileattr_get0 PROTO ((const char *filename,
73				   const char *attrname));
74
75/* This is just a string manipulation function; it does not manipulate
76   file attributes as such.
77
78   LIST is in the format
79
80   ATTRNAME NAMEVALSEP ATTRVAL {ENTSEP ATTRNAME NAMEVALSEP ATTRVAL}
81
82   And we want to put in an attribute with name NAME and value VAL,
83   replacing the already-present attribute with name NAME if there is
84   one.  Or if VAL is NULL remove attribute NAME.  Return a new
85   malloc'd list; don't muck with the one passed in.  If we are removing
86   the last attribute return NULL.  LIST can be NULL to mean that we
87   started out without any attributes.
88
89   Examples:
90
91   fileattr_modify ("abc=def", "xxx", "val", '=', ';')) => "abc=def;xxx=val"
92   fileattr_modify ("abc=def", "abc", "val", '=', ';')) => "abc=val"
93   fileattr_modify ("abc=v1;def=v2", "abc", "val", '=', ';'))
94     => "abc=val;def=v2"
95   fileattr_modify ("abc=v1;def=v2", "def", "val", '=', ';'))
96     => "abc=v1;def=val"
97   fileattr_modify ("abc=v1;def=v2", "xxx", "val", '=', ';'))
98     => "abc=v1;def=v2;xxx=val"
99   fileattr_modify ("abc=v1;def=v2;ghi=v3", "def", "val", '=', ';'))
100     => "abc=v1;def=val;ghi=v3"
101*/
102
103extern char *fileattr_modify PROTO ((char *list, const char *attrname,
104				     const char *attrval, int namevalsep,
105				     int entsep));
106
107/* Set attribute ATTRNAME for file FILENAME to ATTRVAL.  If ATTRVAL is NULL,
108   the attribute is removed.  Changes are not written to disk until the
109   next call to fileattr_write.  If FILENAME is NULL, set attributes for
110   files created in the future.  If ATTRVAL is NULL, remove that attribute.  */
111extern void fileattr_set PROTO ((const char *filename, const char *attrname,
112				 const char *attrval));
113
114/* Get all the attributes for file FILENAME.  They are returned as malloc'd
115   data in an unspecified format which is guaranteed only to be good for
116   passing to fileattr_setall, or NULL if no attributes.  If FILENAME is
117   NULL, get default attributes.  */
118extern char *fileattr_getall PROTO ((const char *filename));
119
120/* Set the attributes for file FILENAME to ATTRS, overwriting all previous
121   attributes for that file.  ATTRS was obtained from a previous call to
122   fileattr_getall (malloc'd data or NULL).  */
123extern void fileattr_setall PROTO ((const char *filename, const char *attrs));
124
125/* Set the attributes for file FILENAME in whatever manner is appropriate
126   for a newly created file.  */
127extern void fileattr_newfile PROTO ((const char *filename));
128
129/* Write out all modified attributes.  */
130extern void fileattr_write PROTO ((void));
131
132/* Free all memory allocated by fileattr_*.  */
133extern void fileattr_free PROTO ((void));
134
135#define FILEATTR_H 1
136#endif /* fileattr.h */
137