unlink()--Remove Link to File

 #include <unistd.h>

 int unlink(const char *path);  

The unlink() function removes a directory entry that refers to a file. This unlink() deletes the link named by path and decrements the link count for the file itself.

If the link count becomes zero and no job currently has the file open, the file itself is deleted. The space occupied by the file is freed for new use, and the current contents of the file are lost. If one or more jobs have the file open when the last link is removed, unlink() removes the link, but the file itself is not removed until the last job closes the file.

unlink() cannot be used to remove a directory; use rmdir() instead.

If path refers to a symbolic link, unlink() removes the symbolic link but not a file or directory named by the contents of the symbolic link.

If unlink() succeeds, the change and modification times for the parent directory are updated. If the link count of the file is not zero, the change time for the file is also updated. If unlink() fails, the link is not removed.

If the file is checked out, unlink() fails with the [EBUSY] error. If the file is marked "read-only", unlink() fails with the [EROOBJ] error.

Parameters

path

(Input) A pointer to the null-terminated path name of the file to be unlinked.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgUnlink()--Remove Link to File (using NLS-enabled path name) for a description and an example of supplying the path in any CCSID.

Authorities

Note: Adopted authority is not used.

Authorization Required for unlink() (excluding QSYS.LIB, independent ASP QSYS.LIB, QDLS and QOPT)

Authorization Required for unlink() in the QSYS.LIB and independent ASP QSYS.LIB File Systems

Object Referred to	Authority Required	errno
Each directory in the path name preceding the object to be unlinked	*X	EACCES
Parent directory of the object to be unlinked	See Note	EACCES
Object to be unlinked	See Note	EACCES
Note: The required authorization varies for each object type. See the DLTxxx commands in the iSeries Security Reference book for details.

Authorization Required for unlink() in the QDLS File System

Authorization Required for unlink() in the QOPT File System

Return Value

0

unlink() was successful.

-1

unlink() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If unlink() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   • Where multiple threads exist in the job.
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   The link to a file cannot be removed when a job has the file open.

   The following object types cannot be unlinked when there are secondary threads active in the job: *CFGL, *CNNL, *COSD, *CTLD, *DEVD, *IPXD, *LIND, *MODD, *NTBD, *NWID, *NWSD. The operation will fail with error code [ENOTSAFE].

3. QDLS File System Differences

   The link to a document cannot be removed when a job has the document open (returns the [EBUSY] error).

4. QOPT File System Differences

   The change and modification times of the parent directory are not updated.

   The link to a file cannot be removed when a job has the file open.

5. The link to a file cannot be removed if the file is a DataLink column in an SQL table and a row in that SQL table references this file.

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
  
• close()--Close File or Socket Descriptor
  
• link()--Create Link to File
  
• open()--Open File
  
• QlgOpen()--Open a File (using NLS-enabled path name)
  
• QlgRmdir()--Remove Directory (using NLS-enabled path name)
  
• QlgUnlink()--Remove Link to File (using NLS-enabled path name)
  
• rmdir()--Remove Directory

Example

See Code disclaimer information for information pertaining to code examples.

The following example removes a link to a file:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>

main() {
  int file_descriptor;
  char fn[]="unlink.file";

  if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(file_descriptor);
    if (unlink(fn) != 0)
      perror("unlink() error");
  }
}