Función CreateHardLinkA (winbase.h)

Artículo
03/13/2024

Establece un vínculo físico entre un archivo existente y un archivo nuevo. Esta función solo se admite en el sistema de archivos NTFS y solo para archivos, no directorios.

Para realizar esta operación como una operación de transacción, use la función CreateHardLinkTransacted .

Sintaxis

BOOL CreateHardLinkA(
  [in] LPCSTR                lpFileName,
  [in] LPCSTR                lpExistingFileName,
       LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parámetros

[in] lpFileName

Nombre del nuevo archivo.

Este parámetro puede incluir la ruta de acceso, pero no puede especificar el nombre de un directorio.

De forma predeterminada, el nombre está limitado a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, anteponga "\\?\\ " a la ruta de acceso. Para obtener más información, vea Nomenclatura de archivos, rutas de acceso y espacios de nombres.

Sugerencia

A partir de Windows 10, versión 1607, puede optar por quitar la limitación de MAX_PATH sin prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Nombres de archivos, rutas de acceso y espacios de nombres para obtener más información.

[in] lpExistingFileName

Nombre del archivo existente.

Este parámetro puede incluir la ruta de acceso no puede especificar el nombre de un directorio.

Sugerencia

lpSecurityAttributes

Reservados; debe ser NULL.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero (0). Para obtener información de error extendida, llame a GetLastError.

El número máximo de vínculos físicos que se pueden crear con esta función es de 1023 por archivo. Si se crean más de 1023 vínculos para un archivo, se produce un error.

Si pasa un nombre mayor que MAX_PATH caracteres al parámetro lpFileName o lpExistingFileName de la versión ANSI de esta función o a la versión Unicode de esta función sin prepending "\\?\\" a la ruta de acceso, la función devuelve ERROR_PATH_NOT_FOUND.

Comentarios

Cualquier entrada de directorio para un archivo creado con CreateFile o CreateHardLink es un vínculo físico a un archivo asociado. Un vínculo físico adicional que se crea con la función CreateHardLink permite tener varias entradas de directorio para un archivo, es decir, varios vínculos físicos al mismo archivo, que pueden ser nombres diferentes en el mismo directorio, o los mismos nombres o diferentes en directorios diferentes. Sin embargo, todos los vínculos físicos a un archivo deben estar en el mismo volumen.

Dado que los vínculos físicos son solo entradas de directorio para un archivo, muchos cambios en ese archivo son visibles instantáneamente para las aplicaciones que acceden a él a través de los vínculos físicos que hacen referencia a él. Sin embargo, el tamaño de entrada del directorio y la información del atributo solo se actualizan para el vínculo a través del cual se realizó el cambio.

El descriptor de seguridad pertenece al archivo al que apunta un vínculo físico. El propio vínculo es solo una entrada de directorio y no tiene un descriptor de seguridad. Por lo tanto, al cambiar el descriptor de seguridad de un vínculo físico, se cambia el descriptor de seguridad del archivo subyacente y todos los vínculos físicos que apuntan al archivo permiten el acceso recién especificado. No se pueden proporcionar descriptores de seguridad diferentes a un archivo por vínculo físico.

Esta función no modifica el descriptor de seguridad del archivo al que se va a vincular, incluso si se pasa información del descriptor de seguridad en el parámetro lpSecurityAttributes .

Use DeleteFile para eliminar vínculos físicos. Puede eliminarlos en cualquier orden, independientemente del orden en que se creen.

Las marcas, los atributos, el acceso y el uso compartido especificados en CreateFile funcionan por archivo. Es decir, si abre un archivo que no permite el uso compartido, otra aplicación no puede compartir el archivo mediante la creación de un nuevo vínculo físico al archivo.

Cuando se crea un vínculo físico en el sistema de archivos NTFS, la información del atributo de archivo de la entrada de directorio solo se actualiza cuando se abre el archivo o cuando se llama a GetFileInformationByHandle con el identificador de un archivo específico.

Comportamiento de vínculo simbólico: si la ruta de acceso apunta a un vínculo simbólico, la función crea un vínculo físico al vínculo simbólico.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	No
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	No
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	No

Tenga en cuenta que SMB 3.0 no admite la creación de vínculos físicos en recursos compartidos con capacidad de disponibilidad continua.

Ejemplos

El siguiente fragmento de código muestra cómo llamar a CreateHardLink para que no modifique el descriptor de seguridad de un archivo. El parámetro pszExistingFileName puede ser el nombre de archivo original o cualquier vínculo existente a un archivo. Una vez ejecutado este código, pszNewLinkName hace referencia al archivo.

  BOOL fCreatedLink = CreateHardLink( pszNewLinkName, 
                                      pszExistingFileName, 
                                      NULL ); // reserved, must be NULL

  if ( fCreatedLink == FALSE )
   {
    ;// handle error condition
   }

Nota

El encabezado winbase.h define CreateHardLink como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll