coreutils: dirname invocation

1 
1 18.2 ‘dirname’: Strip last file name component
1 ==============================================
1 
1 ‘dirname’ prints all but the final slash-delimited component of each
1 NAME.  Slashes on either side of the final component are also removed.
1 If the string contains no slash, ‘dirname’ prints ‘.’ (meaning the
1 current directory).  Synopsis:
1 
1      dirname [OPTION] NAME...
1 
1    NAME need not be a file name, but if it is, this operation
1 effectively lists the directory that contains the final component,
1 including the case when the final component is itself a directory.
1 
1    Together, ‘basename’ and ‘dirname’ are designed such that if ‘ls
1 "$name"’ succeeds, then the command sequence ‘cd "$(dirname "$name")";
1 ls "$(basename "$name")"’ will, too.  This works for everything except
1 file names containing a trailing newline.
1 
1    POSIX allows the implementation to define the results if NAME is
1 ‘//’.  With GNU ‘dirname’, the result is ‘//’ on platforms where // is
1 distinct from /, and ‘/’ on platforms where there is no difference.
1 
11    The program accepts the following option.  Also see ⇒Common
 options.
1 
1 ‘-z’
1 ‘--zero’
1      Output a zero byte (ASCII NUL) at the end of each line, rather than
1      a newline.  This option enables other programs to parse the output
1      even when that output would contain data with embedded newlines.
1 
1    An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1 
1    Examples:
1 
1      # Output "/usr/bin".
1      dirname /usr/bin/sort
1      dirname /usr/bin//.//
1 
1      # Output "dir1" followed by "dir2"
1      dirname dir1/str dir2/str
1 
1      # Output ".".
1      dirname stdio.h
1