fgetws ()- 從串流讀取寬字串

線上編輯

格式

#include <wchar.h>
#include <stdio.h>
wchar_t *fgetws(wchar_t *wcs, int n, FILE *stream);

語言層次

ANSI

安全執行緒

是

區分語言環境

此函數的行為可能受現行語言環境的 LC_CTYPE 種類影響。 如果在編譯指令上指定 LOCALETYPE (*LOCALEUCS2) 或 LOCALETYPE (*LOCALEUTF) ，則現行語言環境的 LC_UNI_CTYPE 種類也可能影響行為。 在編譯指令上指定 LOCALETYPE (*CLD) 時，無法使用此函數。 如需相關資訊，請參閱 瞭解 CCSID 及語言環境。

Integrated File System 介面

在編譯指令上指定 SYSIFCOPT (*NOIFSIO) 時，無法使用此函數。

寬字元函數

如需相關資訊，請參閱 寬字元 。

說明

fgetws() 函數從 串流指向的串流中最多讀取比 n 指定的寬字元數少 1 個。 fgetws() 函數會在 WEOF 之後停止讀取字元，或在讀取換行字元 (保留) 之後停止讀取字元。 它會在讀取至陣列的最後一個寬字元之後立即新增空值寬字元。 除非發生錯誤，否則 fgetws() 函數會前進檔案位置。 如果發生錯誤，則檔案位置未定義。

將非寬字元函數與相同串流上的 fgetws() 函數搭配使用會導致未定義的行為。 在呼叫 fgetws() 函數之後，除非已達到 WEOF ，否則請先清除緩衝區或重新定位串流指標，然後再呼叫串流的寫入函數。 在串流上執行寫入作業之後，請清除緩衝區或重新定位串流指標，然後再呼叫 fgetws() 函數。

附註: 如果在相同串流上的後續讀取作業之間變更現行語言環境，則可能會發生未定義的結果。

回覆值

如果成功， fgetws() 函數會傳回寬字串 wcs的指標。 如果在將任何寬字元讀入 wcs之前遇到 WEOF ，則 wcs 的內容保持不變，且 fgetws() 函數會傳回空值指標。 如果在資料已讀入字串緩衝區之後達到 WEOF ，則 fgetws() 函數會傳回字串緩衝區的指標，以指出成功。 後續呼叫會傳回 NULL ，因為在未讀取任何資料的情況下，就會呼叫 WEOF。

如果發生讀取錯誤，則 wcs 的內容不確定，且 fgetws() 函數會傳回 NULL。 如果發生編碼錯誤 (將寬字元轉換為多位元組字元) ， fgetws() 函數會將錯誤碼設為 EILSEQ 並傳回 NULL。

如果 n 等於 1 ，則 wcs 緩衝區只有結束空值字元的空間，且不會從串流中讀取任何內容。 (這類作業仍被視為讀取作業，因此除非清除緩衝區或先重新定位串流指標，否則它無法立即遵循寫入作業。) 如果 n 大於 1 ，則只有在發生 I/O 錯誤時，或在從串流讀取資料之前達到 WEOF 時， fgetws() 函數才會失敗。

使用 ferror() 和 feof() 函數來區分讀取錯誤和 WEOF。 只有在嘗試讀取超過資料最後一個位元組時，才會達到 WEOF 錯誤。 讀取並包含資料的最後一個位元組不會開啟 WEOF 指示器。

如需 fgetws()的錯誤碼值的相關資訊，請參閱 fgetwc ()-從串流讀取寬字元。

範例

此範例會開啟檔案，讀取檔案內容，然後列印檔案內容。
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
 
int main(void)
{
   FILE    *stream;
   wchar_t  wcs[100];
 
   if (NULL == (stream = fopen("fgetws.dat", "r"))) {
      printf("Unable to open: \"fgetws.dat\"\n");
      exit(1);
   }
 
   errno = 0;
   if (NULL == fgetws(wcs, 100, stream)) {
      if (EILSEQ == errno) {
         printf("An invalid wide character was encountered.\n");
         exit(1);
      }
      else if (feof(stream))
              printf("End of file reached.\n");
           else
              perror("Read error.\n");
   }
   printf("wcs = \"%ls\"\n", wcs);
   fclose(stream);
   return 0;
 
   /************************************************************
      Assuming the file fgetws.dat contains:
 
      This test string should not return -1
 
      The output should be similar to:
 
      wcs = "This test string should not return -1"
   ************************************************************/
}

相關資訊