If oid is a graphic tag, this function returns the path name for the graphic. If oid is invalid, or is not the oid for a graphic tag, this function returns the null string. If the path name comes from a tag attribute value, this function expands character and entity references.

The function attempts to resolve relative paths using the base URI for the location where the graphics element is located before attempting to resolve the path using the document directory or directories from the graphicspath. The base URI and the document directory are often the same, but may be different when the graphic element is contained in an XInclude, file entity, or other included content.

In addition, if the graphics reference value is a relative filename that cannot be resolved to an absolute path name because the file does not exist, the string returned will be the absolute path name for the document directory concatenated to the relative name. This prevents the relative name from being inadvertently resolved to a file in the current working directory. However, if the document in question has not been saved, there is no document directory and the graphic name (which may be an absolute or a relative name) will be returned as is.

Consider the following markup:

If the oid for this tag is contained in the variable o, and you call oid_graphic_pathname:

then the path name would contain the string:

Note that the & character entity reference was expanded to the & character.