Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
strtoacl(3C)							  strtoacl(3C)

       strtoacl(),  strtoaclpatt(),  aclentrystart[]  -	convert	string form to
       access control list (ACL) structure (HFS	File System only)

       converts	an access control list from exact symbolic (string)  represen-
       tation  to structure form.  It parses the input string and verifies its
       validity.  Optionally it	applies	the entries in the string as a	series
       of changes to an	existing ACL.

       converts	 an  access control list pattern from symbolic (string)	repre-
       sentation to structure form.  It	parses the input string	 and  verifies
       its validity.

       The external array only valid until the next call of either routine, is
       useful for error	reporting.  See	ERRORS below.

       The ``operator''	and ``short'' symbolic forms of	ACLs and ACL  patterns
       (described  in  acl(5))	are acceptable as input	strings.  If the first
       non-whitespace character	in string is the ACL or	ACL pattern in	string
       must be in short	form.  Otherwise operator form is assumed.

       takes  a	 pointer  to  the string to be converted, and a	pointer	to the
       first element of	an array of ACL	entries	initially containing the indi-
       cated  number  (nentries)  of valid entries (zero or more).  This array
       can grow	to the indicated number	of entries (maxentries).   also	 takes
       file  user ID (fuid) and	group ID (fgid)	values to substitute for char-
       acters in string	and returns the	resulting number of entries in

       Redundant entries (identical user ID and	group ID values	after process-
       ing  characters)	 are  combined,	so that	contains unique	entries	in the
       order encountered.  If a	new entry is mentioned,	it is added to the end
       of the array.

       differs	from  because  it  processes an	ACL pattern instead of an ACL.
       Since modification of an	existing initial ACL is	not useful, it is  not

       Entries	with matching user and group ID	values are not combined.  Each
       entry input yields one entry in the returned array.

       The character for user and group	IDs (see acl(5)) is converted to  spe-
       cial  values (or	respectively, defined in not to	specific user or group
       names provided by the caller.  Thus, need not be	called to reparse  the
       ACL  pattern for	each file, but the caller must handle the special val-
       ues when	comparing an ACL pattern to an ACL.

       Wildcard	user names, group names, and mode values are supported,	as are
       absent mode parts; see acl(5).

       returns	a  different  structure	than The acl_entry_patt	structure con-
       tains onmode and	offmode	masks rather than a single mode	value.

       In operator form	input, operators have a	different effect on

	      Sets bits	in both	the
		   onmode and offmode fields appropriately, replacing existing
		   bits	in the entry, including	any set	by earlier operators.

	      Sets bits	in
		   onmode and clears the same bits in offmode.

	      Sets bits	in
		   offmode and clears the same bits in onmode.

	      In  short	 form  input, the mode is treated like the operator in
	      operator form.

       For both	routines, a non-specific user or group ID of is	 converted  to
       or respectively.	 For only, a wildcard user or group ID of is converted
       to or respectively.  The	values are defined in

       Entries can appear in string in any order.  string can  contain	redun-
       dant  entries,  and  in operator	form only, redundant and operators for
       ACL entry mode modifications (in	exact form) or mode bit	inclusions/ex-
       clusions	 (in  patterns).  Entries or modifications are applied left to

   Suggested Use
       To build	a new ACL (ACL pattern)	array using define with	 as  many  en-
       tries  as desired.  Pass	it to with nentries set	to zero	only) and max-
       entries set to the number of elements in

       To have modify a	file's existing	ACL, define with the maximum  possible
       number  of  entries see Call (see getacl(2)) to read the	file's ACL and
       (see stat(2)) to	get the	file's owner and group	IDs.   Then  pass  the
       current	number	of entries, the	current	ACL, and the ID	values to with
       maxentries set to

       If succeeds, the	resulting ACL can be passed safely to (see  setacl(2))
       because	all  redundancies  (if any) have been resolved.	 However, note
       that since neither nor validate user and	group ID values, if the	values
       are not acceptable to the system, fails.

   Performance Trick
       Normally	 replaces user and group names of with specific	user and group
       ID values, and also combines redundant entries.	Therefore, calling and
       for  each of a series of	files to which an ACL is being applied is sim-
       plest, although time consuming.

       If string contains no character,	or if the caller merely	wants to  com-
       pare one	ACL against another (and will handle the special case itself),
       it is sufficient	to call	once, and pointless to call for	each file.  To
       determine  this,	 call  the first time with fuid	set to and fgid	set to
       Repeated	calls with file-specific fuid and fgid values are needed  only
       if  the	special	values of fuid and fgid	appear in and the caller needs
       an exact	ACL to set on each file; see EXAMPLES below.

       If appears in string and	will be	used later for a call to it is	neces-
       sary to call again to reparse the ACL string for	each file.  It is pos-
       sible that not all redundant entries were combined the first  time  be-
       cause  the  names were not resolved to specific IDs.  This also compli-
       cates comparisons between two ACLs.  Furthermore, the caller cannot  do
       the combining later because operator information	from operator form in-
       put might be lost.

       and convert string form to access control list (ACL) structure.

       If succeeds, it returns the number of entries in	the resulting ACL (ACL
       pattern), always	equal to or greater than nentries (zero).

       also  sets values in global array to point to the start of each pattern
       entry it	parsed in string, in some cases	including leading or  trailing
       whitespace.   It	 only  sets  a	number of pointers equal to its	return
       value plus one (never more than + 1).  The last valid element points to
       the  null  character at the end of string.  After calling an entry pat-
       tern's corresponding input string can be	used by	the caller  for	 error
       reporting  by (temporarily) putting a null at the start of the next en-
       try pattern in string.

       If an error occurs, and return a	negative value and the content	of  is
       undefined (was probably altered).  To help with error reporting in this
       case, and are set to point to the start of the  current	and  next  en-
       tries, respectively, being parsed when the error	occurred.  If the cur-
       rent entry does not start with points to	the  next  null	 character  or
       comma  at  or  after  Otherwise,	 it points to the next null, or	to the
       character following the next

       The following values are	returned in case of error:

	      -1   Syntax error: entry doesn't start with as expected in short

	      -2   Syntax  error:  entry doesn't end with as expected in short

	      -3   Syntax error: user name is not terminated by	a dot.

	      -4   only) Syntax	error: group name is not terminated by an  op-
		   erator  in operator-form input or a comma in	short-form in-

	      -5   Syntax error: user name is null.

	      -6   Syntax error: group name is null.

	      -7   Invalid user	name (not found	in file	and not	a  valid  num-

	      -8   Invalid  group name (not found in file and not a valid num-

	      -9   Syntax error: invalid mode character, other	than  (allowed
		   in short form only),	(allowed in patterns only), (to	end an
		   entry in operator form), or	(to  end  an  entry  in	 short
		   form).  Or, or is followed by other mode characters.

	      -10  The resulting ACL would have	more than maxentries entries.

       The  following  code fragment converts an ACL from a string to an array
       of entries using	an fuid	of 103 for the file's owner and	fgid of	45 for
       the file's group.

       The  following  code gets the ACL, fuid,	and fgid for file modifies the
       ACL using a description string, and changes the ACL on file to  be  the
       new version.

       The following code fragment calls with special values of	fuid and fgid,
       then checks to see if they show up in

       The following code fragment converts an ACL pattern from	a string to an
       array of	pattern	entries.

       The  following  code fragment inside a loop checks an entry pattern and
       variable	names) against an entry	in a file's ACL	variable names)	 using
       the file's user and group IDs variable names).

       and are only supported on HFS file system on standalone HP-UX operating

       and were	developed by HP.

       getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C),  setaclen-
       try(3C),	acl(5),	thread_safety(5).



Want to link to this manual page? Use this URL:

home | help