.\" Modified from man(1) of FreeBSD, the NetBSD mdoc.template and mdoc.samples
.\" See man mdoc for the short list of editing options
.Dd June 1, 2024     \" DATE
.Dt FILEURLTOOL 1           \" Program name and manual section number
.Os Darwin
.Sh NAME                 \" Section Header - required - don't modify
.Nm fileurltool
.\" The following lines are read in generating the apropos database.
.\" Use only key words here as the database is built on these.
.\" Use .Nm macro to designate other names for the documented program.
.Nd a tool to exercise the NSURL/CFURL resource property APIs
.Sh SYNOPSIS             \" Section Header - required - don't modify
.Nm
.Op Fl by-path
.Op Fl by-ref
.Op Fl cf1
.Op Fl cfm
.Op Fl ns1
.Op Fl nsm
.Op Fl print-type
.Op Fl print-cache
.Op Fl leaks
.Op Ar get URL KEY ...
.Op Ar set URL KEY=VALUE
.Op Ar check URL
.Op Ar getflags URL
.Op Ar getvolflags URL
.Op Ar keys
.Sh DESCRIPTION          \" Section Header - required - don't modify
.Nm
exercises the NSURL getResourceValue:forKey:error: and
.Fn CFURLCopyResourcePropertyForKey
APIs on given file: scheme URLs.
.Pp                      \" Inserts a space
This tool accepts of the commands
.Ar get set check getflags getvolflags keys
each of which has certain options.
.Bl -tag -width -indent  \" Begins a tagged list
.It Ar get URL KEY ...               \" Each item preceded by .It macro
Get the resource properties with the constant names
.Ar KEY
as described below, for the given
.Ar URL
as described and display each value.  If no
.Ar
KEY
is provided, then print out most of the known values for the item.
.It Ar set URL KEY=VALUE
Set the resource properties for the
.Ar KEY
to the value
.Ar VALUE
where
.Ar VALUE
is a format appropriate for the type of data for the
.Ar KEY
on the given
.Ar URL
.It Ar check URL
Check if the given URL is reachable and print the result.
.It Ar getflags URL
Get the resource property flags for the given URL and display them.
.It Ar getvolflags URL
Get the resource volume property flags for the given URL and display them.
.El                      \" Ends the list
.Pp
The values for
.Ar KEY
can be the same as the constant string in the appropriate API, either the CF or NS varients, or it can be a string containing letters, digits, "_" or ".", which will be treated as if it was the value of a constant in the API.
.Pp
Examples of valid keys include NSURLNameKey, NSURLCreationDateKey.
.Pp
The values for
.Ar VALUE
depend on the data type asssociated with the value in the API.  If the data type is a string, then the string is just used; if it is a boolean then 1 or YES or 0 or NO are appropriate.  If the type is a number,
.Pp
A list of flags and their descriptions:
.Bl -tag -width -indentXXX  \" Differs from above in tag removed
.It Fl by-path                 \"-a flag as a list item
Create a file-path URL which uses the file path string
.It Fl by-ref
Create a file-reference URL before calling the API
.It Fl cf1
Use\
.Fn CFURLCopyResourcePropertyForKey
/
.Fn CFURLSetResourcePropertyForKey
API
.It Fl cfm
Use
.Fn CFURLCopyResourcePropertiesForKeys
/
.Fn CFURLSetResourcePropertiesForKeys
API
.It Fl ns1
Use NSURL's  getResourceValue:forKey:error: and setResourceValue:forKey:error: API
.It Fl nsm
Use NSURL's resourceValuesForKeys:error: and setResourceValues:error: API
.El